tui-cs/Terminal.Gui · error · ArgumentOutOfRangeException

Maximum sixel palette colors must be greater than zero.

Error message

Maximum sixel palette colors must be greater than zero.

What it means

Thrown by the ImageView.MaxSixelPaletteColors setter when value <= 0. The property caps how many colors the sixel encoder will quantise the image into during redraws; zero or negative makes quantisation undefined, so it is rejected before the field is updated and InvalidateScaledImage is called. Default is DEFAULT_MAX_SIXEL_PALETTE_COLORS (64).

Source

Thrown at Terminal.Gui/Views/ImageView/ImageView.cs:220

        }
    }

    /// <summary>
    ///     Gets or sets the maximum number of colors to use when encoding ImageView sixel output.
    /// </summary>
    /// <remarks>
    ///     The default is 64 colors to keep interactive ImageView redraws responsive. The effective
    ///     encoder palette is also limited by <see cref="SixelSupportResult.MaxPaletteColors"/> and by
    ///     the configured <see cref="SixelEncoder.Quantizer"/> <c>MaxColors</c>.
    /// </remarks>
    public int MaxSixelPaletteColors
    {
        get;
        set
        {
            if (value <= 0)
            {
                throw new ArgumentOutOfRangeException (nameof (value), @"Maximum sixel palette colors must be greater than zero.");
            }

            if (field == value)
            {
                return;
            }

            field = value;
            InvalidateScaledImage ();
        }
    } = DEFAULT_MAX_SIXEL_PALETTE_COLORS;

    /// <summary>
    ///     Gets or sets whether sixel rendering may upscale the visible image region above its source pixel size.
    /// </summary>
    /// <remarks>
    ///     The default is <see langword="true"/> so the image fills the Viewport at <see cref="ZoomLevel"/> 1.
    ///     Set to <see langword="false"/> to avoid encoding more pixels than the source image provides during fit-to-view

View on GitHub (pinned to 2e47b11478)

Solutions

1. Set a positive value (1..256 typically): imageView.MaxSixelPaletteColors = Math.Max(16, detectedColors);
2. Coerce config input: var colors = configSection.Colors > 0 ? configSection.Colors : 64;
3. If deriving from capability detection, fall back to the default when detection returns 0/null.

Example fix

// before
imageView.MaxSixelPaletteColors = detected.MaxColors; // 0 when detection failed

// after
imageView.MaxSixelPaletteColors = detected is { MaxColors: > 0 } d ? d.MaxColors : 64;

int colors = config.Colors > 0 ? config.Colors : 64;
imageView.MaxSixelPaletteColors = colors;

static bool IsValidPaletteSize(int n) => n > 0;

When it happens

Trigger: Setting MaxSixelPaletteColors to 0 or a negative int, often from a config value, a computed count from an empty collection (.Count on an empty palette), or an off-by-one.

Common situations: Theme/config JSON feeding 0 when the key is missing; deriving the value from detected terminal palette size before detection completed (returned 0); unit test with an unset field defaulting to 0.

Related errors

• Zoom level must be a finite number.
• The source stream must be seekable (CanSeek property)
• No raster graphics support available.
• value
• value

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