dotnet/maui · error · BuildException

XC0126

XC0126

Error message

Resources in ResourceDictionary require a x:Key attribute.

What it means

Raised by the XAML compiler when a node placed inside a ResourceDictionary has no x:Key attribute and its CLR type has no ResourceDictionary.Add(T) overload that would accept it implicitly. The task probes for an Add method whose single parameter matches the node's type; only when none exists does it throw, forcing an explicit key.

Source

Thrown at src/Controls/src/Build.Tasks/SetPropertiesVisitor.cs:1948

			if (node.Properties.TryGetValue(XmlName.xKey, out INode value))
			{
				var valueNode = value as ValueNode ?? throw new BuildException(XKeyNotLiteral, lineInfo, null);
				var key = valueNode.Value as string;
				var names = context.Cache.GetResourceNamesInUse(parent);
				if (names.Contains(key))
					throw new BuildException(ResourceDictDuplicateKey, lineInfo, null, key);
				return true;
			}

			//is there a RD.Add() overrides that accepts this ?
			var nodeTypeRef = context.Variables[node].VariableType;
			var module = context.Body.Method.Module;
			if (module.ImportMethodReference(context.Cache,
											 module.GetTypeDefinition(context.Cache, ("Microsoft.Maui.Controls", "Microsoft.Maui.Controls", "ResourceDictionary")),
											 methodName: "Add",
											 parameterTypes: [nodeTypeRef]) != null)
				return true;
			throw new BuildException(ResourceDictMissingKey, lineInfo, null);
		}

		static IEnumerable<Instruction> Add(VariableDefinition parent, XmlName propertyName, INode node, IXmlLineInfo iXmlLineInfo, ILContext context)
		{
			var module = context.Body.Method.Module;
			var elementNode = node as ElementNode;
			var vardef = context.Variables[elementNode];

			TypeReference propertyType;
			foreach (var instruction in GetPropertyValue(parent, propertyName, context, iXmlLineInfo, out propertyType))
				yield return instruction;

			if (CanAddToResourceDictionary(parent, propertyType, elementNode, iXmlLineInfo, context))
			{
				foreach (var instruction in AddToResourceDictionary(parent, elementNode, iXmlLineInfo, context))
					yield return instruction;
				yield break;
			}

View on GitHub (pinned to f377ff1c5e)

Solutions

1. Add an x:Key attribute to the resource element, e.g. <Style x:Key="RedButton" TargetType="Button">.
2. If the type is meant to be implicitly addable, add a public Add(T) instance method to your ResourceDictionary subclass that accepts that type.
3. Move the resource out of the ResourceDictionary into a property/ContentPage.Resources context that does not require keys.

Example fix

<!-- before -->
<ResourceDictionary>
    <Style TargetType="Button">
        <Setter Property="BackgroundColor" Value="Red"/>
    </Style>
</ResourceDictionary>
<!-- after -->
<ResourceDictionary>
    <Style x:Key="RedButton" TargetType="Button">
        <Setter Property="BackgroundColor" Value="Red"/>
    </Style>
</ResourceDictionary>

// Lint rule: any element directly under <ResourceDictionary> must either carry x:Key
// or be a type for which ResourceDictionary.Add(T) exists (e.g. implicitly-keyed styles).
static bool NeedsKey(string elementName) => elementName is "Style" or "DataTemplate";

When it happens

Trigger: A child element of a ResourceDictionary whose type is not one of the implicitly-keyed kinds (the task finds no matching Add overload) and which carries no XmlName.xKey property, so the final 'throw new BuildException(ResourceDictMissingKey...)' is reached.

Common situations: Declaring a Style without x:Key (styles in a RD are not implicitly keyed unless they are the implicit default style target); adding a custom type to a RD before giving the RD an Add(T) overload; pasting resources from a ContentPage.Resources scope where keys were optional into a ResourceDictionary where they are required.

Related errors

• XC0125
• XC0128
• XC0127
• XC0066
• XC0000

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