tui-cs/Terminal.Gui · error · InvalidOperationException

Background ImageView rendering failed.

Error message

Background ImageView rendering failed.

What it means

Thrown by ImageView.FailBackgroundRender, a continuation invoked on the main thread when a background raster-graphics render Task faulted. It wraps the original exception (passed as InnerException) to mark the failure point in the render pipeline. The real cause is in InnerException — typically an encoder failure (Sixel/Kitty), an out-of-memory image scale, or a disposed resource during async render. By design ImageView re-throws rather than silently showing a stale frame.

Source

Thrown at Terminal.Gui/Views/ImageView/ImageView.Render.cs:334

            return;
        }

        RenderRequest? currentRequest = CreateRenderRequest (result.Key.UseRasterGraphics);

        if (UseBackgroundRendering && currentRequest?.Key == result.Key)
        {
            ApplyRenderResult (result);
        }

        StartNextQueuedRenderOrFinish (result.Key);
        SetNeedsDraw ();
    }

    private void FailBackgroundRender (Exception exception)
    {
        StartNextQueuedRenderOrFinish (_backgroundRenderKey);

        throw new InvalidOperationException ("Background ImageView rendering failed.", exception);
    }

    private void StartNextQueuedRenderOrFinish (RenderKey? completedKey)
    {
        RenderRequest? nextRequest = null;

        lock (_renderLock)
        {
            if (_queuedRenderRequest is { } queuedRequest && queuedRequest.Key != completedKey)
            {
                nextRequest = queuedRequest;
                _queuedRenderRequest = null;
            }
            else
            {
                _queuedRenderRequest = null;
                _backgroundRenderKey = null;
                _backgroundRenderRunning = false;

View on GitHub (pinned to 2e47b11478)

Solutions

1. Inspect the InnerException first — that is the real fault; fix the root cause (image too large, encoder option mismatch).
2. Disable background rendering (UseBackgroundRendering = false) to get synchronous errors at the call site instead of on the main-thread continuation.
3. Reduce the workload: lower MaxSixelPaletteColors, downscale the source image, or raise the terminal's reported color capability.
4. Ensure the ImageView and its Image are not disposed while a render Task is pending (await/await shutdown of rendering before Dispose).

Example fix

// before
imageView.UseBackgroundRendering = true; // async fault surfaces as 162

// after
imageView.UseBackgroundRendering = false; // synchronous, InnerException visible
// or catch and inspect:
try { app.Run<MyWindow>(); }
catch (InvalidOperationException ex) when (ex.Message == "Background ImageView rendering failed.")
{
    Log.Error(ex.InnerException, "render failed");
}

imageView.UseBackgroundRendering = false; // surface errors synchronously instead

try
{
    app.Run<MyWindow>();
}
catch (InvalidOperationException ex) when (ex.Message == "Background ImageView rendering failed.")
{
    // InnerException is the real cause
    Log.Error(ex.InnerException, "ImageView background render failed");
}

When it happens

Trigger: UseBackgroundRendering == true and the background Task throws: SixelEncoder producing an invalid palette, a GDI/ImageSharp scaling failure, the image being disposed mid-render, or the terminal reporting raster support that the encoder then violates. Fires via CompleteBackgroundRender -> app.Invoke(() => FailBackgroundRender(...)).

Common situations: Large images on terminals with limited sixel palette/colors; CI/headless runs where the driver fakes graphics support; racing disposal of the ImageView while a render is in flight; version skew between driver capability detection and encoder behaviour.

Related errors

• AdornmentView can only render to their Parent or Parent's Su
• Adornment must be of type Border
• Zoom level must be a finite number.
• Maximum sixel palette colors must be greater than zero.
• No raster graphics support available.

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