dotnet/maui · error · InvalidOperationException

ToolbarResource must be set to a androidx.appcompat.widget.T

Error message

ToolbarResource must be set to a androidx.appcompat.widget.Toolbar

What it means

Thrown during OnCreate when inflating the layout referenced by ToolbarResource raises an Android.Views.InflateException. The framework wraps that exception to clarify that the inflated layout must be an androidx.appcompat.widget.Toolbar. The InflateException itself usually means the layout resource is missing, references an unknown view, or a dependency (e.g., AppCompat/Material library) is absent.

Source

Thrown at src/Compatibility/Core/src/Android/AppCompat/FormsAppCompatActivity.cs:233

			if (_toolbarResource == 0)
			{
				ToolbarResource = Resource.Layout.toolbar;
			}

			if (_tabLayoutResource == 0)
			{
				_tabLayoutResource = Resource.Layout.tabbar;
			}

			if (ToolbarResource != 0)
			{
				try
				{
					bar = LayoutInflater.Inflate(ToolbarResource, null).JavaCast<AToolbar>();
				}
				catch (global::Android.Views.InflateException ie)
				{
					throw new InvalidOperationException("ToolbarResource must be set to a androidx.appcompat.widget.Toolbar", ie);
				}

				if (bar == null)
					throw new InvalidOperationException("ToolbarResource must be set to a androidx.appcompat.widget.Toolbar");
			}
			else
			{
				bar = new AToolbar(this);
			}

			SetSupportActionBar(bar);

			Profile.FramePartition("SetContentView");
			_layout = new ARelativeLayout(BaseContext);
			SetContentView(_layout);

			Profile.FramePartition("OnStateChanged");
			Microsoft.Maui.Controls.Application.Current = null;

View on GitHub (pinned to f377ff1c5e)

Solutions

Ensure ToolbarResource points to a layout whose root element is androidx.appcompat.widget.Toolbar (the default Resource.Layout.toolbar).
Verify the AndroidX AppCompat and Material NuGet packages are referenced and version-aligned across the solution.
If using ProGuard/R8, add keep rules for androidx.appcompat.widget.Toolbar and its inflator.
Inspect the inner InflateException (passed as the InnerException) for the exact inflation error and resolve the referenced view or resource.

Example fix

// before
[Activity(ToolbarResource = Resource.Layout.my_broken_layout)]

// after
[Activity] // lets Forms default ToolbarResource = Resource.Layout.toolbar
// or explicitly
[Activity(ToolbarResource = Resource.Layout.toolbar)]

Defensive patterns

Strategy: try-catch

Validate before calling

// Validate the layout resource exists and its root is a toolbar before OnCreate runs.
bool IsToolbarLayout(int resourceId)
{
    try
    {
        var view = LayoutInflater.Inflate(resourceId, null);
        return view is AndroidX.AppCompat.Widget.Toolbar;
    }
    catch
    {
        return false;
    }
}

Try / catch

try
{
    // OnCreate runs normally
}
catch (InvalidOperationException ex) when (ex.Message.Contains("ToolbarResource"))
{
    // Fallback: unset ToolbarResource so Forms creates a default AToolbar
    ToolbarResource = 0;
    Log.Warn(nameof(FormsAppCompatActivity), $"Toolbar layout invalid, falling back to default toolbar. Inner: {ex.InnerException?.Message}");
    throw; // or re-run OnCreate logic with default toolbar
}

Prevention

Pin AndroidX AppCompat and Material NuGet versions consistently across all projects in the solution.
Add ProGuard/R8 keep rules for androidx.appcompat.widget.Toolbar.
Validate toolbar layout resources in a release-config integration test.
Inspect the InnerException (InflateException) for the root cause before changing the layout.

When it happens

Trigger: ToolbarResource is set to a layout ID whose root tag is not a toolbar widget, or to a resource that does not exist. A missing or version-mismatched AndroidX AppCompat/Material NuGet prevents the toolbar widget from inflating. Proguard/R8 stripping the toolbar class can also cause inflation failure.

Common situations: Upgrading AndroidX AppCompat or Material packages to incompatible versions. Setting ToolbarResource to a custom layout that was removed or renamed. ProGuard/R8 configuration stripping AToolbar in release builds. Setting ToolbarResource = Resource.Layout.NonExistentLayout.

Related errors

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