{"record":{"id":"27c137252d0e76f9","repo":"tui-cs/Terminal.Gui","slug":"background-imageview-rendering-failed","errorCode":null,"errorMessage":"Background ImageView rendering failed.","messagePattern":"Background ImageView rendering failed\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"Terminal.Gui/Views/ImageView/ImageView.Render.cs","lineNumber":334,"sourceCode":"            return;\n        }\n\n        RenderRequest? currentRequest = CreateRenderRequest (result.Key.UseRasterGraphics);\n\n        if (UseBackgroundRendering && currentRequest?.Key == result.Key)\n        {\n            ApplyRenderResult (result);\n        }\n\n        StartNextQueuedRenderOrFinish (result.Key);\n        SetNeedsDraw ();\n    }\n\n    private void FailBackgroundRender (Exception exception)\n    {\n        StartNextQueuedRenderOrFinish (_backgroundRenderKey);\n\n        throw new InvalidOperationException (\"Background ImageView rendering failed.\", exception);\n    }\n\n    private void StartNextQueuedRenderOrFinish (RenderKey? completedKey)\n    {\n        RenderRequest? nextRequest = null;\n\n        lock (_renderLock)\n        {\n            if (_queuedRenderRequest is { } queuedRequest && queuedRequest.Key != completedKey)\n            {\n                nextRequest = queuedRequest;\n                _queuedRenderRequest = null;\n            }\n            else\n            {\n                _queuedRenderRequest = null;\n                _backgroundRenderKey = null;\n                _backgroundRenderRunning = false;","sourceCodeStart":316,"sourceCodeEnd":352,"githubUrl":"https://github.com/tui-cs/Terminal.Gui/blob/2e47b11478db083499917f2ad27c34d30efb0df1/Terminal.Gui/Views/ImageView/ImageView.Render.cs#L316-L352","documentation":"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.","triggerScenarios":"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(...)).","commonSituations":"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.","solutions":["Inspect the InnerException first — that is the real fault; fix the root cause (image too large, encoder option mismatch).","Disable background rendering (UseBackgroundRendering = false) to get synchronous errors at the call site instead of on the main-thread continuation.","Reduce the workload: lower MaxSixelPaletteColors, downscale the source image, or raise the terminal's reported color capability.","Ensure the ImageView and its Image are not disposed while a render Task is pending (await/await shutdown of rendering before Dispose)."],"exampleFix":"// before\nimageView.UseBackgroundRendering = true; // async fault surfaces as 162\n\n// after\nimageView.UseBackgroundRendering = false; // synchronous, InnerException visible\n// or catch and inspect:\ntry { app.Run<MyWindow>(); }\ncatch (InvalidOperationException ex) when (ex.Message == \"Background ImageView rendering failed.\")\n{\n    Log.Error(ex.InnerException, \"render failed\");\n}","handlingStrategy":"try-catch","validationCode":"imageView.UseBackgroundRendering = false; // surface errors synchronously instead","typeGuard":null,"tryCatchPattern":"try\n{\n    app.Run<MyWindow>();\n}\ncatch (InvalidOperationException ex) when (ex.Message == \"Background ImageView rendering failed.\")\n{\n    // InnerException is the real cause\n    Log.Error(ex.InnerException, \"ImageView background render failed\");\n}","preventionTips":["Always inspect InnerException — it carries the root cause.","Disable UseBackgroundRendering during development to get errors at the call site.","Downscale large images and lower MaxSixelPaletteColors to avoid encoder failures.","Ensure the ImageView is not disposed while a background render Task is pending."],"tags":["imageview","async","rendering","diagnostic"],"backgroundTag":null,"analyzedSha":"2e47b11478db083499917f2ad27c34d30efb0df1","analyzedAt":"2026-08-13T19:20:08.826Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}