dotnet/maui · error · NotSupportedException

Namescopes are not supported. Please enable the feature swit

Error message

Namescopes are not supported. Please enable the feature switch 'Microsoft.Maui.RuntimeFeature.AreNamescopesSupported' to keep using namescopes.

What it means

Thrown by Element.FindByName when the runtime feature switch 'Microsoft.Maui.RuntimeFeature.AreNamescopesSupported' evaluates to false. MAUI uses feature switches for trimming/AOT scenarios; namescope support (x:Name lookup, INameScope registration) can be disabled to reduce app size. By default SupportNamescopesByDefault is true, so this only fires when the switch is explicitly turned off in the app's runtimeconfig or .csproj.

Source

Thrown at src/Controls/src/Core/Element/Element.cs:568

		/// page, content view, or data template defines its own namescope.
		/// </para>
		/// <para>
		/// The search is limited to elements that have been registered in the same namescope, which includes:
		/// </para>
		/// <list type="bullet">
		/// <item><description>Elements with x:Name attributes defined in XAML within the same namescope</description></item>
		/// <item><description>Elements manually registered using <see cref="INameScope.RegisterName(string, object)"/></description></item>
		/// <item><description>Child elements and their descendants within the same namescope boundary</description></item>
		/// </list>
		/// <para>
		/// Elements in different namescopes (such as different pages or data templates) are not accessible
		/// from each other through this method.
		/// </para>
		/// </remarks>
		public object FindByName(string name)
		{
			if (!RuntimeFeature.AreNamescopesSupported)
				throw new NotSupportedException("Namescopes are not supported. Please enable the feature switch 'Microsoft.Maui.RuntimeFeature.AreNamescopesSupported' to keep using namescopes.");

			var namescope = GetNameScope() ?? transientNamescope;
			if (namescope == null)
				throw new InvalidOperationException("this element is not in a namescope");
			return namescope.FindByName(name);
		}

		/// <inheritdoc/>
		void INameScope.RegisterName(string name, object scopedElement)
		{
			if (!RuntimeFeature.AreNamescopesSupported)
				throw new NotSupportedException("Namescopes are not supported. Please enable the feature switch 'Microsoft.Maui.RuntimeFeature.AreNamescopesSupported' to keep using namescopes.");

			var namescope = GetNameScope() ?? throw new InvalidOperationException("this element is not in a namescope");
			namescope.RegisterName(name, scopedElement);
		}

		/// <inheritdoc/>

View on GitHub (pinned to f377ff1c5e)

Solutions

Enable the feature switch in your .csproj: <RuntimeHostConfigurationOption Include="Microsoft.Maui.RuntimeFeature.AreNamescopesSupported" Value="true" />
Check at startup: ensure no code or runtimeconfig.json sets 'Microsoft.Maui.RuntimeFeature.AreNamescopesSupported' to false.
Replace FindByName calls with direct references held from XAML code-behind partial fields, or use VisualDiagnostics/visual-tree traversal that does not depend on namescopes.
If disabling namescopes intentionally, remove all x:Name usages and FindByName/RegisterName calls from your XAML and code-behind.

Example fix

// before
var btn = (Button)myElement.FindByName("submitButton");
// after — enable the switch in .csproj, or reference directly
var btn = submitButton; // x:Name partial field still works when switch is on

Defensive patterns

Strategy: validation

Validate before calling

if (!Microsoft.Maui.RuntimeFeature.AreNamescopesSupported)
    throw new InvalidOperationException("Namescope feature switch is disabled; cannot use FindByName.");

Try / catch

try { var found = element.FindByName(name); }
catch (NotSupportedException ex) when (ex.Message.Contains("AreNamescopesSupported"))
{
    // namescope feature switch is off; fall back to direct references
}

Prevention

Verify the feature switch value in runtimeconfig before relying on namescopes.
Prefer x:Name code-behind partial fields which compile to direct references where possible.
Document which XAML/code paths depend on namescopes when publishing trimmed apps.

When it happens

Trigger: Calling element.FindByName("name") on any Element instance while AppContext switch 'Microsoft.Maui.RuntimeFeature.AreNamescopesSupported' is set to false. This happens after the app declares the feature switch as false via runtimeconfig.json, .csproj <RuntimeHostConfigurationOption>, or AppContext.SetSwitch at startup.

Common situations: Publishing a MAUI app with AOT/trimming enabled and the feature switch defaulting off; upgrading MAUI versions where the switch default changed; explicitly disabling namescopes in a publish profile to reduce binary size; calling FindByName in code-behind after the XAML compiler has been configured for size optimization.

Related errors

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