dotnet/maui · error · InvalidOperationException

MauiContext not set

Error message

MauiContext not set

What it means

Thrown by the VisualElementRenderer base class when the MauiContext property is accessed but _mauiContext has not been set. MauiContext is the bridge between the MAUI abstraction layer and the platform-specific context (DI services, handlers, etc.). Every renderer needs it to resolve handlers, converters, and other services. The property getter throws InvalidOperationException if null, indicating the renderer was used before the framework assigned its context.

Source

Thrown at src/Controls/src/Core/Compatibility/Handlers/VisualElementRenderer.cs:59

			[AutomationProperties.HelpTextProperty.PropertyName] = MapAutomationPropertiesHelpText,
			[AutomationProperties.LabeledByProperty.PropertyName] = MapAutomationPropertiesLabeledBy,
#pragma warning restore CS0618 // Type or member is obsolete
#endif
		};

		public static CommandMapper<TElement, IPlatformViewHandler> VisualElementRendererCommandMapper = new CommandMapper<TElement, IPlatformViewHandler>(ViewHandler.ViewCommandMapper);

#if IOS || MACCATALYST
		WeakReference<TElement>? _virtualView;
		TElement? _tempElement;
#else
		TElement? _virtualView;
#endif
		IMauiContext? _mauiContext;
		internal IPropertyMapper _mapper;
		internal readonly CommandMapper? _commandMapper;
		internal readonly IPropertyMapper _defaultMapper;
		protected IMauiContext MauiContext => _mauiContext ?? throw new InvalidOperationException("MauiContext not set");
#if IOS || MACCATALYST
		public TElement? Element => _tempElement ?? (_virtualView is not null && _virtualView.TryGetTarget(out var target) ? target : null);
#else
		public TElement? Element => _virtualView;
#endif
		protected bool AutoPackage { get; set; } = true;

#if ANDROID
		public VisualElementRenderer(Context context) : this(context, VisualElementRendererMapper, VisualElementRendererCommandMapper)
		{
		}
#else
		public VisualElementRenderer() : this(VisualElementRendererMapper, VisualElementRendererCommandMapper)
		{
		}
#endif

View on GitHub (pinned to f377ff1c5e)

Solutions

1. Avoid accessing MauiContext in the renderer constructor — defer to OnElementChanged or later lifecycle methods.
2. Ensure MauiProgram is fully configured (UseMauiApp, builder.Build()) before any rendering occurs.
3. If using a custom renderer, ensure it is registered through the standard handler/registration pipeline so the framework sets MauiContext.
4. Verify that the app's startup sequence creates the MAUI application before any platform view tries to use it.
5. Check MAUI version compatibility — update to a stable release if using pre-release builds with lifecycle bugs.

Example fix

// before (custom renderer)
public class MyRenderer : VisualElementRenderer<MyView>
{
    public MyRenderer(Context context) : base(context)
    {
        var service = MauiContext.Services; // throws — context not set yet
    }
}

// after
public class MyRenderer : VisualElementRenderer<MyView>
{
    public MyRenderer(Context context) : base(context) { }

    protected override void OnElementChanged(ElementChangedEventArgs<MyView> e)
    {
        base.OnElementChanged(e);
        if (e.NewElement != null)
        {
            var service = MauiContext.Services; // safe — context is set by now
        }
    }
}

// In custom renderers, check before accessing MauiContext
if (_mauiContext == null)
    return; // defer until context is set
var service = MauiContext.Services;

public bool HasMauiContext => _mauiContext != null;

When it happens

Trigger: At line 59: `protected IMauiContext MauiContext => _mauiContext ?? throw new InvalidOperationException("MauiContext not set")`. Accessing MauiContext before the framework has called SetMauiContext (or equivalent). This typically happens when: (1) a renderer method is called during construction before context assignment; (2) a custom renderer accesses MauiContext in an overridden method that fires too early in the lifecycle; (3) the handler's platform view was created outside the normal MAUI handler pipeline; (4) DI/initialization ordering failed in MauiProgram.

Common situations: 1) Custom renderer accessing MauiContext in its constructor or an early lifecycle method (e.g., OnElementChanged before base sets context). 2) Creating platform views manually instead of through the handler infrastructure. 3) MAUI initialization (MauiProgram.CreateMauiApp) incomplete or failed, so context was never propagated. 4) Using the compatibility VisualElementRenderer outside the standard handler registration. 5) Lifecycle ordering issues in specific MAUI versions.

Related errors

• NavigationPage must have a root Page before being used. Eith
• call Forms.Init() before this
• NavigationPage must have a root Page before being used. Eith
• LoadView must be called before accessing View
• Reuse of the Shell Renderer is not supported

AI-assisted analysis of dotnet/maui@f377ff1c5e (2026-08-13). Data as JSON: /api/errors/283c573535eaab14. Report an issue: GitHub.