tui-cs/Terminal.Gui · critical · ApplicationException

Failed to set screenBuffer console mode, error code: {Marsha

Error message

Failed to set screenBuffer console mode, error code: {Marshal.GetLastWin32Error()}.

What it means

This error is thrown by WindowsOutput when the Windows console API SetConsoleMode fails on the newly-created screen buffer during driver initialization on a legacy console. The library creates its own screen buffer to bypass legacy console limitations and needs to disable line-wrap on it. If SetConsoleMode returns false, the Win32 error code is captured via Marshal.GetLastWin32Error and reported.

Source

Thrown at Terminal.Gui/Drivers/WindowsDriver/WindowsOutput.cs:131

        if (IsLegacyConsole)
        {
            CreateScreenBuffer ();

            if (!GetConsoleMode (_screenBuffer, out mode))
            {
                throw new ApplicationException ($"Failed to get screenBuffer console mode, error code: {Marshal.GetLastWin32Error ()}.");
            }

#pragma warning disable IDE1006 // Naming Styles
            const uint ENABLE_WRAP_AT_EOL_OUTPUT = 0x0002;
#pragma warning restore IDE1006 // Naming Styles

            mode &= ~ENABLE_WRAP_AT_EOL_OUTPUT; // Disable wrap

            if (!SetConsoleMode (_screenBuffer, mode))
            {
                throw new ApplicationException ($"Failed to set screenBuffer console mode, error code: {Marshal.GetLastWin32Error ()}.");
            }
        }
        else
        {
            if (Environment.GetEnvironmentVariable ("VSAPPIDNAME") is null)
            {
                //Enable alternative screen buffer.
                Console.Out.Write (EscSeqUtils.CSI_SaveCursorAndActivateAltBufferNoBackscroll);
            }
            else
            {
                _foreground = Console.ForegroundColor;
                _background = Console.BackgroundColor;
            }
        }

        GetSize ();
    }

View on GitHub (pinned to 2e47b11478)

Solutions

Verify the application is running in a real console window (not redirected to a pipe or file) and that ENABLE_VIRTUAL_TERMINAL_PROCESSING is available; on Windows 10 1709+ the legacy path is rarely needed.
Check for stdout redirection -- if stdout is redirected (e.g., 'myapp > out.txt'), the screen buffer handle may be invalid; run in a true terminal.
Update to a newer Windows version or enable the legacy console host fallback that supports CreateConsoleScreenBuffer + SetConsoleMode.
If unavoidable, switch to the AnsiDriver via DriverRegistry configuration so the legacy WindowsOutput codepath is not taken.

Example fix

// before -- running with redirected stdout triggers legacy path failure
app.Run<MyWindow>();

// after -- ensure stdout is a real console; or select the ANSI driver explicitly
Application.ForceDriver = "Ansi";
using IApplication app = Application.Create().Init();
app.Run<MyWindow>();

Defensive patterns

Strategy: validation

Validate before calling

if (!OperatingSystem.IsWindows() || Console.IsOutputRedirected) { /* select AnsiDriver or skip live driver */ }
if (!IsAttachedToTerminal) { /* use headless/test mode */ }

Try / catch

try { using IApplication app = Application.Create().Init(); app.Run<MyWindow>(); }
catch (ApplicationException ex) when (ex.Message.Contains("screenBuffer console mode"))
{ Console.Error.WriteLine($"Console mode setup failed (Win32). Use a real terminal. {ex.Message}"); }

Prevention

Run the app in a real console window, not with redirected stdout.
On Windows, ensure VT processing is available (Windows 10 1709+) so the legacy screen-buffer codepath is avoided.
Use the AnsiDriver via Application.ForceDriver if the legacy WindowsOutput path is problematic.
Check Console.IsOutputRedirected before initializing the driver.

When it happens

Trigger: Occurs exclusively in the WindowsOutput constructor (Terminal.Gui/Drivers/WindowsDriver/WindowsOutput.cs:131) when IsLegacyConsole is true (i.e., ENABLE_VIRTUAL_TERMINAL_PROCESSING is not set on the original console). After CreateScreenBuffer() and a successful GetConsoleMode, SetConsoleMode is called with the ENABLE_WRAP_AT_EOL_OUTPUT bit cleared. The throw fires only if that P/Invoke returns false.

Common situations: Running under a non-standard Windows console host (e.g., conhost with restricted mode), running inside an RDP/session where screen-buffer creation partially fails, antivirus or endpoint-protection intercepting console handles, or running on Windows Server Core where VT processing is unavailable and screen buffer setup is fragile.

Related errors

AI-assisted analysis of tui-cs/Terminal.Gui@2e47b11478 (2026-08-13). Data as JSON: /api/errors/91af5b5085c2b225. Report an issue: GitHub.