{"record":{"id":"685c7cb054d8e461","repo":"spectreconsole/spectre.console","slug":"alternate-buffers-are-not-supported-by-your-termin","errorCode":null,"errorMessage":"Alternate buffers are not supported by your terminal.","messagePattern":"Alternate buffers are not supported by your terminal\\.","errorType":"exception","errorClass":"NotSupportedException","httpStatus":null,"severity":"error","filePath":"src/Spectre.Console/Extensions/AnsiConsoleExtensions.Screen.cs","lineNumber":24,"sourceCode":"public static partial class AnsiConsoleExtensions\n{\n    /// <summary>\n    /// Switches to an alternate screen buffer if the terminal supports it.\n    /// </summary>\n    /// <param name=\"console\">The console.</param>\n    /// <param name=\"action\">The action to execute within the alternate screen buffer.</param>\n    public static void AlternateScreen(this IAnsiConsole console, Action action)\n    {\n        ArgumentNullException.ThrowIfNull(console);\n\n        if (!console.Profile.Capabilities.Ansi)\n        {\n            throw new NotSupportedException(\"Alternate buffers are not supported since your terminal does not support ANSI.\");\n        }\n\n        if (!console.Profile.Capabilities.AlternateBuffer)\n        {\n            throw new NotSupportedException(\"Alternate buffers are not supported by your terminal.\");\n        }\n\n        // Switch to alternate screen\n        console.WriteAnsi(w =>\n        {\n            w.EnterAltScreen();\n            w.CursorHome();\n        });\n\n        try\n        {\n            // Execute custom action\n            action();\n        }\n        finally\n        {\n            // Switch back to primary screen\n            console.WriteAnsi(w => w.ExitAltScreen());","sourceCodeStart":6,"sourceCodeEnd":42,"githubUrl":"https://github.com/spectreconsole/spectre.console/blob/0acc92fada6c42f13984e79c2b5f3d993bdfb099/src/Spectre.Console/Extensions/AnsiConsoleExtensions.Screen.cs#L6-L42","documentation":"Thrown by the AlternateScreen extension when the terminal supports ANSI but not an alternate screen buffer (Capabilities.AlternateBuffer is false). It is a NotSupportedException: the underlying terminal advertises no alt-buffer capability, so the feature cannot be used on it.","triggerScenarios":"Calling console.AlternateScreen(action) when Profile.Capabilities.Ansi is true but Profile.Capabilities.AlternateBuffer is false.","commonSituations":"A minimal/legacy terminal that answers ANSI but not the alt-buffer queries; an enriched profile that disabled AlternateBuffer; redirected-but-ANSI-forced environments; terminals where capability detection fell back to conservative defaults.","solutions":["Check console.Profile.Capabilities.AlternateBuffer before calling AlternateScreen and fall back to a full-screen redraw path","Use a terminal known to support alternate buffers (most modern terminals do)","Do not force capabilities off; let detection run, or set AlternateBuffer via the appropriate profile path if your terminal supports it"],"exampleFix":"// before\nconsole.AlternateScreen(() => DrawMenu(console)); // throws on a no-alt-buffer terminal\n\n// after\nif (console.Profile.Capabilities.AlternateBuffer)\n{\n    console.AlternateScreen(() => DrawMenu(console));\n}\nelse\n{\n    DrawMenu(console); // fallback: redraw in the main buffer\n}","handlingStrategy":"type-guard","validationCode":"if (console.Profile.Capabilities.Ansi && console.Profile.Capabilities.AlternateBuffer)\n{\n    console.AlternateScreen(() => Draw(console));\n}\nelse\n{\n    Draw(console); // fallback in main buffer\n}","typeGuard":"static bool SupportsAltBuffer(IAnsiConsole c) => c.Profile.Capabilities.AlternateBuffer;","tryCatchPattern":"try\n{\n    console.AlternateScreen(() => Draw(console));\n}\ncatch (NotSupportedException ex) when (ex.Message.Contains(\"Alternate buffers are not supported by your terminal\"))\n{\n    Draw(console); // fallback: redraw in the main buffer\n}","preventionTips":["Check AlternateBuffer capability before calling AlternateScreen","Provide a full-screen redraw fallback for terminals without an alt buffer","Test on the minimal terminal you intend to support"],"tags":["ansi","terminal-capabilities","alternate-buffer","fallback"],"backgroundTag":null,"analyzedSha":"0acc92fada6c42f13984e79c2b5f3d993bdfb099","analyzedAt":"2026-08-13T18:27:21.983Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}