{"record":{"id":"2a66b7c99d8a5fc1","repo":"felixse/FluentTerminal","slug":"failed-to-start-the-shell-process-please-check-yo","errorCode":null,"errorMessage":"Failed to start the shell process. Please check your shell settings.{Environment.NewLine}Tried to start: {request.Profile.Location} \"\"{request.Profile.Arguments}\"\"","messagePattern":"Failed to start the shell process\\. Please check your shell settings\\.(.+?)Tried to start: (.+?) \"\"(.+?)\"\"","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"critical","filePath":"FluentTerminal.SystemTray/Services/WinPty/WinPtySession.cs","lineNumber":64,"sourceCode":"                var args = request.Profile.Arguments;\n\n                if (!string.IsNullOrWhiteSpace(request.Profile.Location))\n                {\n                    args = $\"\\\"{request.Profile.Location}\\\" {args}\";\n                }\n\n                spawnConfigHandle = winpty_spawn_config_new(WINPTY_SPAWN_FLAG_AUTO_SHUTDOWN, request.Profile.Location, args, cwd, terminalsManager.GetDefaultEnvironmentVariableString(request.Profile.EnvironmentVariables), out errorHandle);\n                if (errorHandle != IntPtr.Zero)\n                {\n                    throw new Exception(winpty_error_msg(errorHandle));\n                }\n\n                _stdin = CreatePipe(winpty_conin_name(_handle), PipeDirection.Out);\n                _stdout = CreatePipe(winpty_conout_name(_handle), PipeDirection.In);\n\n                if (!winpty_spawn(_handle, spawnConfigHandle, out IntPtr process, out IntPtr thread, out int procError, out errorHandle))\n                {\n                    throw new Exception($@\"Failed to start the shell process. Please check your shell settings.{Environment.NewLine}Tried to start: {request.Profile.Location} \"\"{request.Profile.Arguments}\"\"\");\n                }\n\n                var shellProcessId = ProcessApi.GetProcessId(process);\n                _shellProcess = Process.GetProcessById(shellProcessId);\n                _shellProcess.EnableRaisingEvents = true;\n                _shellProcess.Exited += _shellProcess_Exited;\n\n                if (!string.IsNullOrWhiteSpace(request.Profile.Location))\n                {\n                    ShellExecutableName = Path.GetFileNameWithoutExtension(request.Profile.Location);\n                }\n                else\n                {\n                    ShellExecutableName = request.Profile.Arguments.Split(' ')[0];\n                }\n            }\n            finally\n            {","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/felixse/FluentTerminal/blob/ba83ec485eea8d8ee65825711731300bee2e76ed/FluentTerminal.SystemTray/Services/WinPty/WinPtySession.cs#L46-L82","documentation":"Thrown by WinPtySession.Start when winpty_spawn (the call that actually launches the shell process inside the pseudoconsole) returns false. Unlike the config errors, this throw does not use winpty_error_msg; it emits a fixed message telling the user to check shell settings and echoing the attempted Location and Arguments.","triggerScenarios":"winpty_spawn(_handle, spawnConfigHandle, ...) returns false: the configured shell executable does not exist, is not executable, the path is wrong, or Windows refused to create the process. The procError out-value holds the OS error but is not included in the message.","commonSituations":"Profile.Location points to a missing or wrong shell (e.g. old bash.exe path, wsl.exe not installed); the executable path has a typo; the shell binary was moved/uninstalled; permissions prevent execution.","solutions":["Verify Profile.Location is an existing, executable file (e.g. C:\\Windows\\System32\\cmd.exe, or the real bash.exe/wsl.exe path).","If Location is empty, ensure Arguments names a command resolvable by the system.","Include procError in the thrown message to expose the OS-level reason (ERROR_FILE_NOT_FOUND, access denied).","Re-select the shell in the profile editor to fix a stale path."],"exampleFix":"// before\nif (!winpty_spawn(_handle, spawnConfigHandle, out IntPtr process, out IntPtr thread, out int procError, out errorHandle))\n    throw new Exception($@\"Failed to start the shell process. Please check your shell settings.{Environment.NewLine}Tried to start: {request.Profile.Location} \"\"{request.Profile.Arguments}\"\"\");\n\n// after - surface the OS error code for diagnosis\nthrow new Exception($@\"Failed to start the shell process (OS error {procError}). Please check your shell settings.{Environment.NewLine}Tried to start: {request.Profile.Location} \"\"{request.Profile.Arguments}\"\"\");","handlingStrategy":"validation","validationCode":"// Confirm the shell exists and is executable before spawning.\nif (!string.IsNullOrWhiteSpace(request.Profile.Location) && !File.Exists(request.Profile.Location))\n    throw new System.IO.FileNotFoundException($\"Shell executable not found: {request.Profile.Location}\", request.Profile.Location);","typeGuard":null,"tryCatchPattern":"try { session.Start(request, manager); }\ncatch (Exception ex) when (ex.Message.Contains(\"Failed to start the shell process\")) { logger.Error(ex, \"spawn failed\"); notifyUser(\"Could not start the configured shell. Check shell settings.\"); }","preventionTips":["Verify Profile.Location is an existing, executable file.","Re-select the shell in the profile editor if the path is stale.","Include procError (the OS error) in the thrown message for diagnosis.","Ensure Arguments reference a resolvable command when Location is empty."],"tags":["winpty","native","terminal-backend","shell","process-spawn","profile"],"backgroundTag":null,"analyzedSha":"ba83ec485eea8d8ee65825711731300bee2e76ed","analyzedAt":"2026-08-13T21:23:15.467Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}