AvaloniaUI/Avalonia · critical · InvalidOperationException

Android backend wasn't initialized. Make sure .UseAndroid()

Error message

Android backend wasn't initialized. Make sure .UseAndroid() was executed.

What it means

Thrown by TopLevelImpl.Compositor when AndroidPlatform.Compositor is null, meaning the Android platform backend was never initialized. Avalonia.Android requires that the application builder calls .UseAndroid() (which registers AndroidPlatform and creates the Compositor) before any TopLevel is used.

Source

Thrown at src/Android/Avalonia.Android/Platform/SkiaPlatform/TopLevelImpl.cs:107

        public Action<RawInputEventArgs>? Input { get; set; }

        public Action<Rect>? Paint { get; set; }

        public Action<Size, WindowResizeReason>? Resized { get; set; }

        public Action<double>? ScalingChanged { get; set; }

        public View? View => _view;

        internal InvalidationAwareSurfaceView? InternalView => _view;

        public double DesktopScaling => RenderScaling;
        public IPlatformHandle Handle { get; }

        public IPlatformRenderSurface[] Surfaces { get; }

        public Compositor Compositor => AndroidPlatform.Compositor ??
            throw new InvalidOperationException("Android backend wasn't initialized. Make sure .UseAndroid() was executed.");

        public Point PointToClient(PixelPoint point)
        {
            return point.ToPoint(RenderScaling);
        }

        public PixelPoint PointToScreen(Point point)
        {
            return PixelPoint.FromPoint(point, RenderScaling);
        }

        public void SetCursor(ICursorImpl? cursor)
        {
            //still not implemented
        }

        public void SetInputRoot(IInputRoot inputRoot)
        {

View on GitHub (pinned to 11c5427268)

Solutions

1. Ensure your Activity extends AvaloniaMainActivity<T> (or AvaloniaFragmentActivity) so .UseAndroid() runs in OnCreate before any view is created.
2. If building AppBuilder manually, chain .UseAndroid() before .Setup().
3. Defer any Avalonia view/TopLevel creation until after AppBuilder.Setup() has completed (e.g. inside AvaloniaMainActivity.CreateAppBuilder or OnCreate post-setup).
4. In unit tests, initialize the Android platform via the test bootstrap before constructing views.

Example fix

// before
public class MainActivity : Activity
{
    protected override void OnCreate(Bundle? b)
    {
        base.OnCreate(b);
        var view = new AvaloniaView(this); // no UseAndroid() ever
        SetContentView(view);
    }
}

// after
public class MainActivity : AvaloniaMainActivity<MyApp>
{
    // UseAndroid() is called by the base class automatically
}

// verify the backend is initialized before using any TopLevel
if (AvaloniaLocator.Current.GetService<AndroidPlatform>()?.Compositor is null)
    throw new InvalidOperationException("Call AppBuilder.UseAndroid() before creating views.");

static bool IsAndroidBackendReady()
    => AvaloniaLocator.Current.GetService<AndroidPlatform>()?.Compositor is not null;

When it happens

Trigger: Accessing TopLevelImpl.Compositor (transitively, most rendering and layout operations) before the Avalonia Android platform has been initialized. .UseAndroid() is normally invoked by the generated AvaloniaMainActivity/AppBuilder; omitting it or calling it too late leaves AndroidPlatform.Compositor null.

Common situations: A custom Activity that does not extend AvaloniaMainActivity or AvaloniaFragmentActivity (which call UseAndroid() automatically); building the AppBuilder manually and forgetting .UseAndroid(); initializing a TopLevel (e.g. via tests or eager view construction) before AppBuilder.Setup completes; library code that constructs Avalonia views during static init.

Related errors

• Avalonia Application was not initialized. Make sure you have
• Main activity must implement IActivityResultHandler interfac
• Application.Context.MainLooper was not expected to be null.
• This class should be instanciated from the UI thread
• AndroidPlatformOptions.RenderingMode must not be empty or nu

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