AvaloniaUI/Avalonia · error · InvalidOperationException

AndroidPlatformOptions.RenderingMode has a value of "{opts.R

Error message

AndroidPlatformOptions.RenderingMode has a value of "{opts.RenderingMode}", but no options were applied.

What it means

Unlike error 31, here RenderingMode is non-empty, but every requested mode failed to produce a backend: Software was not requested (Software returns null only when listed), EGL's TryCreate returned null, and Vulkan's TryInitialize returned null. The loop falls through with no IPlatformGraphics selected, so the platform throws.

Source

Thrown at src/Android/Avalonia.Android/AndroidPlatform.cs:138

                }

                if (renderingMode == AndroidRenderingMode.Egl)
                {
                    if (EglPlatformGraphics.TryCreate() is { } egl)
                    {
                        return egl;
                    }
                }

                if (renderingMode == AndroidRenderingMode.Vulkan)
                {
                    var vulkan = VulkanSupport.TryInitialize(AvaloniaLocator.Current.GetService<VulkanOptions>() ?? new());
                    if (vulkan != null)
                        return vulkan;
                }
            }

            throw new InvalidOperationException($"{nameof(AndroidPlatformOptions)}.{nameof(AndroidPlatformOptions.RenderingMode)} has a value of \"{string.Join(", ", opts.RenderingMode)}\", but no options were applied.");
        }
    }
}

View on GitHub (pinned to 11c5427268)

Solutions

1. Add AndroidRenderingMode.Software to the RenderingMode list as a guaranteed fallback (it returns a non-null software backend).
2. Diagnose EGL/Vulkan init failures (driver, loader, emulator GPU setting).
3. On emulators, set the AVD to use hardware GLES / host GPU.
4. Install/update the device's GPU drivers and ensure libvulkan.so is present for Vulkan mode.

Example fix

// before
RenderingMode = new List<AndroidRenderingMode> { AndroidRenderingMode.Vulkan };

// after (Vulkan/Egl tried first, software guaranteed)
RenderingMode = new List<AndroidRenderingMode>
{
    AndroidRenderingMode.Vulkan,
    AndroidRenderingMode.Egl,
    AndroidRenderingMode.Software
};

// guarantee a software fallback so the loop never falls through
if (!opts.RenderingMode.Contains(AndroidRenderingMode.Software))
    opts.RenderingMode = opts.RenderingMode.Append(AndroidRenderingMode.Software).ToList();

static bool HasSoftwareFallback(AndroidPlatformOptions o) =>
    o.RenderingMode.Contains(AndroidRenderingMode.Software);

// fallback handled by options; if it still throws, surface GPU-init diagnostics rather than swallow.

When it happens

Trigger: Requesting only hardware modes (Egl and/or Vulkan) where none initializes: EGL context creation fails (no GPU/OpenGL ES), Vulkan device creation fails (no Vulkan loader/driver), and Software is not in the list as a fallback.

Common situations: Running on an emulator without GPU acceleration; a device with a broken GPU driver; missing Vulkan loader; EGL not available (headless). Most commonly fixed by appending AndroidRenderingMode.Software to the list.

Related errors

• AndroidPlatformOptions.RenderingMode must not be empty or nu
• Surface handle can't be 0x0
• HTMLCanvasElement.getContext returned null.
• Unable to obtain ANativeWindow
• TopLevel.InternalView was not expected to be null.

AI-assisted analysis of AvaloniaUI/Avalonia@11c5427268 (2026-08-13). Data as JSON: /api/errors/9e14b9b5399b3fcf. Report an issue: GitHub.