spectreconsole/spectre.console · error · NotSupportedException

Alternate buffers are not supported by your terminal.

Error message

Alternate buffers are not supported by your terminal.

What it means

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.

Source

Thrown at src/Spectre.Console/Extensions/AnsiConsoleExtensions.Screen.cs:24

public static partial class AnsiConsoleExtensions
{
    /// <summary>
    /// Switches to an alternate screen buffer if the terminal supports it.
    /// </summary>
    /// <param name="console">The console.</param>
    /// <param name="action">The action to execute within the alternate screen buffer.</param>
    public static void AlternateScreen(this IAnsiConsole console, Action action)
    {
        ArgumentNullException.ThrowIfNull(console);

        if (!console.Profile.Capabilities.Ansi)
        {
            throw new NotSupportedException("Alternate buffers are not supported since your terminal does not support ANSI.");
        }

        if (!console.Profile.Capabilities.AlternateBuffer)
        {
            throw new NotSupportedException("Alternate buffers are not supported by your terminal.");
        }

        // Switch to alternate screen
        console.WriteAnsi(w =>
        {
            w.EnterAltScreen();
            w.CursorHome();
        });

        try
        {
            // Execute custom action
            action();
        }
        finally
        {
            // Switch back to primary screen
            console.WriteAnsi(w => w.ExitAltScreen());

View on GitHub (pinned to 0acc92fada)

Solutions

1. Check console.Profile.Capabilities.AlternateBuffer before calling AlternateScreen and fall back to a full-screen redraw path
2. Use a terminal known to support alternate buffers (most modern terminals do)
3. Do not force capabilities off; let detection run, or set AlternateBuffer via the appropriate profile path if your terminal supports it

Example fix

// before
console.AlternateScreen(() => DrawMenu(console)); // throws on a no-alt-buffer terminal

// after
if (console.Profile.Capabilities.AlternateBuffer)
{
    console.AlternateScreen(() => DrawMenu(console));
}
else
{
    DrawMenu(console); // fallback: redraw in the main buffer
}

if (console.Profile.Capabilities.Ansi && console.Profile.Capabilities.AlternateBuffer)
{
    console.AlternateScreen(() => Draw(console));
}
else
{
    Draw(console); // fallback in main buffer
}

static bool SupportsAltBuffer(IAnsiConsole c) => c.Profile.Capabilities.AlternateBuffer;

try
{
    console.AlternateScreen(() => Draw(console));
}
catch (NotSupportedException ex) when (ex.Message.Contains("Alternate buffers are not supported by your terminal"))
{
    Draw(console); // fallback: redraw in the main buffer
}

When it happens

Trigger: Calling console.AlternateScreen(action) when Profile.Capabilities.Ansi is true but Profile.Capabilities.AlternateBuffer is false.

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

Related errors

• Alternate buffers are not supported since your terminal does
• Encountered closing tag when none was expected near position
• Unbalanced markup stack. Did you forget to close a tag?
• Encountered malformed markup tag at position {pos}.
• Cannot show selection prompt since the current terminal does

AI-assisted analysis of spectreconsole/spectre.console@0acc92fada (2026-08-13). Data as JSON: /api/errors/685c7cb054d8e461. Report an issue: GitHub.