AvaloniaUI/Avalonia · error · InvalidOperationException

AndroidPlatformOptions.RenderingMode must not be empty or nu

Error message

AndroidPlatformOptions.RenderingMode must not be empty or null

What it means

InitializeGraphics requires the user-supplied AndroidPlatformOptions.RenderingMode collection to be non-null and non-empty; it iterates the list to pick Software/EGL/Vulkan. An empty or null list gives the framework nothing to try, so it throws at the top of InitializeGraphics.

Source

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

                .Bind<PlatformHotkeyConfiguration>().ToSingleton<PlatformHotkeyConfiguration>()
                .Bind<KeyGestureFormatInfo>().ToConstant(new KeyGestureFormatInfo(new Dictionary<Key, string>() { }))
                .Bind<IActivatableLifetime>().ToConstant(new AndroidActivatableLifetime());

            var graphics = InitializeGraphics(Options);
            if (graphics is not null)
            {
                AvaloniaLocator.CurrentMutable.Bind<IPlatformGraphics>().ToConstant(graphics);
            }

            Compositor = new Compositor(graphics);
            AvaloniaLocator.CurrentMutable.Bind<Compositor>().ToConstant(Compositor);
        }
        
        private static IPlatformGraphics? InitializeGraphics(AndroidPlatformOptions opts)
        {
            if (opts.RenderingMode is null || !opts.RenderingMode.Any())
            {
                throw new InvalidOperationException($"{nameof(AndroidPlatformOptions)}.{nameof(AndroidPlatformOptions.RenderingMode)} must not be empty or null");
            }

            foreach (var renderingMode in opts.RenderingMode)
            {
                if (renderingMode == AndroidRenderingMode.Software)
                {
                    return null;
                }

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

                if (renderingMode == AndroidRenderingMode.Vulkan)

View on GitHub (pinned to 11c5427268)

Solutions

Set AndroidPlatformOptions.RenderingMode to at least one valid mode, e.g. new() { AndroidRenderingMode.Egl }.
Use the default AndroidPlatformOptions (which already lists Software + Egl + Vulkan).
Always include AndroidRenderingMode.Software as a guaranteed fallback.
Validate options before handing them to With(new AndroidPlatformOptions { ... }).

Example fix

// before
AppBuilder.Configure<AvaloniaAndroid>()
    .With(new AndroidPlatformOptions { RenderingMode = new List<AndroidRenderingMode>() });

// after (always provide a non-empty list with a software fallback)
AppBuilder.Configure<AvaloniaAndroid>()
    .With(new AndroidPlatformOptions
    {
        RenderingMode = new List<AndroidRenderingMode> { AndroidRenderingMode.Egl, AndroidRenderingMode.Software }
    });

Defensive patterns

Strategy: validation

Validate before calling

// ensure a non-empty rendering-mode list with a software fallback
opts.RenderingMode ??= new List<AndroidRenderingMode>();
if (opts.RenderingMode.Count == 0)
    opts.RenderingMode.Add(AndroidRenderingMode.Software);

Type guard

static bool IsValid(AndroidPlatformOptions o) => o.RenderingMode is not null && o.RenderingMode.Any();

Try / catch

// pure validation — no recoverable catch; fix the options before passing them.

Prevention

Always include AndroidRenderingMode.Software as the last fallback.
Use the default AndroidPlatformOptions.
Validate options in a test.

When it happens

Trigger: Constructing AvaloniaAndroid with AndroidPlatformOptions.RenderingMode == null or an empty IEnumerable (e.g. new() or []). The platform cannot pick a renderer.

Common situations: Overriding default options and forgetting RenderingMode; clearing the list; deserializing options from config that omitted the field; passing new AndroidPlatformOptions() after the default was removed.

Related errors

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