felixse/FluentTerminal · critical · Exception

Failed to start the shell process. Please check your shell s

Error message

Failed to start the shell process. Please check your shell settings.{Environment.NewLine}Tried to start: {request.Profile.Location} ""{request.Profile.Arguments}""

What it means

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.

Source

Thrown at FluentTerminal.SystemTray/Services/WinPty/WinPtySession.cs:64

                var args = request.Profile.Arguments;

                if (!string.IsNullOrWhiteSpace(request.Profile.Location))
                {
                    args = $"\"{request.Profile.Location}\" {args}";
                }

                spawnConfigHandle = winpty_spawn_config_new(WINPTY_SPAWN_FLAG_AUTO_SHUTDOWN, request.Profile.Location, args, cwd, terminalsManager.GetDefaultEnvironmentVariableString(request.Profile.EnvironmentVariables), out errorHandle);
                if (errorHandle != IntPtr.Zero)
                {
                    throw new Exception(winpty_error_msg(errorHandle));
                }

                _stdin = CreatePipe(winpty_conin_name(_handle), PipeDirection.Out);
                _stdout = CreatePipe(winpty_conout_name(_handle), PipeDirection.In);

                if (!winpty_spawn(_handle, spawnConfigHandle, out IntPtr process, out IntPtr thread, out int procError, out errorHandle))
                {
                    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}""");
                }

                var shellProcessId = ProcessApi.GetProcessId(process);
                _shellProcess = Process.GetProcessById(shellProcessId);
                _shellProcess.EnableRaisingEvents = true;
                _shellProcess.Exited += _shellProcess_Exited;

                if (!string.IsNullOrWhiteSpace(request.Profile.Location))
                {
                    ShellExecutableName = Path.GetFileNameWithoutExtension(request.Profile.Location);
                }
                else
                {
                    ShellExecutableName = request.Profile.Arguments.Split(' ')[0];
                }
            }
            finally
            {

View on GitHub (pinned to ba83ec485e)

Solutions

1. Verify Profile.Location is an existing, executable file (e.g. C:\Windows\System32\cmd.exe, or the real bash.exe/wsl.exe path).
2. If Location is empty, ensure Arguments names a command resolvable by the system.
3. Include procError in the thrown message to expose the OS-level reason (ERROR_FILE_NOT_FOUND, access denied).
4. Re-select the shell in the profile editor to fix a stale path.

Example fix

// before
if (!winpty_spawn(_handle, spawnConfigHandle, out IntPtr process, out IntPtr thread, out int procError, out errorHandle))
    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}""");

// after - surface the OS error code for diagnosis
throw 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}""");

// Confirm the shell exists and is executable before spawning.
if (!string.IsNullOrWhiteSpace(request.Profile.Location) && !File.Exists(request.Profile.Location))
    throw new System.IO.FileNotFoundException($"Shell executable not found: {request.Profile.Location}", request.Profile.Location);

try { session.Start(request, manager); }
catch (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."); }

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• winpty_error_msg(errorHandle)
• failed to create pipe
• Could not allocate console for this process.
• Could not get console mode.
• Could not enable virtual terminal processing.

AI-assisted analysis of felixse/FluentTerminal@ba83ec485e (2026-08-13). Data as JSON: /api/errors/2a66b7c99d8a5fc1. Report an issue: GitHub.