spectreconsole/spectre.console · error · NotSupportedException

Alternate buffers are not supported since your terminal does

Error message

Alternate buffers are not supported since your terminal does not support ANSI.

What it means

Thrown by the AlternateScreen extension when the console profile reports no ANSI support (Capabilities.Ansi is false). Alternate screen buffers are implemented with ANSI escape sequences, so without ANSI the feature is unavailable; this is a NotSupportedException, not a usage bug.

Source

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

namespace Spectre.Console;

/// <summary>
/// Contains extension methods for <see cref="IAnsiConsole"/>.
/// </summary>
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();

View on GitHub (pinned to 0acc92fada)

Solutions

1. Force ANSI on in settings: new AnsiConsoleSettings { Ansi = AnsiSupport.Yes } before creating the console
2. Only call AlternateScreen when console.Profile.Capabilities.Ansi is true
3. Redirect-aware: do not use AlternateScreen when Console.IsOutputRedirected
4. On Windows, enable a modern terminal (Windows Terminal) or virtual terminal processing

Example fix

// before
var settings = new AnsiConsoleSettings { Ansi = AnsiSupport.No };
var console = AnsiConsole.Create(settings);
console.AlternateScreen(() => { }); // throws

// after
var settings = new AnsiConsoleSettings { Ansi = AnsiSupport.Yes };
var console = AnsiConsole.Create(settings);
console.AlternateScreen(() => { });

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

static bool SupportsAltScreen(IAnsiConsole c) =>
    c.Profile.Capabilities.Ansi && c.Profile.Capabilities.AlternateBuffer;

try
{
    console.AlternateScreen(() => Draw(console));
}
catch (NotSupportedException ex) when (ex.Message.Contains("does not support ANSI"))
{
    Draw(console); // fallback: redraw in the main buffer
}

When it happens

Trigger: Calling console.AlternateScreen(action) on a console whose Profile.Capabilities.Ansi is false.

Common situations: Output is redirected to a file/pipe so ANSI detection fails; running on a legacy Windows console with ANSI disabled; an explicitly configured AnsiSupport.No profile; CI/headless run where the terminal is not detected as ANSI-capable.

Related errors

• Alternate buffers are not supported by your terminal.
• 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}.
• Output writer was null

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