dotnet/maui · error · BuildException

XC0040

XC0040

Error message

Cannot convert value "{0}" to "{1}".

What it means

XC0040 Conversion thrown by LayoutOptionsConverter when a XAML string does not match any public static field on the Microsoft.Maui.Controls.LayoutOptions type. The converter trims the value, optionally accepts a 'LayoutOptions.' prefix, then resolves the remainder as a static field name. If no matching field exists, the build exception fires.

Source

Thrown at src/Controls/src/Build.Tasks/CompiledConverters/LayoutOptionsConverter.cs:39

				value = value.Trim();

				var parts = value.Split('.');
				if (parts.Length == 1 || (parts.Length == 2 && parts[0] == "LayoutOptions"))
				{
					var options = parts[parts.Length - 1];

					var fieldReference = module.ImportFieldReference(context.Cache, ("Microsoft.Maui.Controls", "Microsoft.Maui.Controls", "LayoutOptions"),
																	 fieldName: options,
																	 isStatic: true);
					if (fieldReference != null)
					{
						yield return Instruction.Create(OpCodes.Ldsfld, fieldReference);
						yield break;
					}
				}
			} while (false);

			throw new BuildException(BuildExceptionCode.Conversion, node, null, value, typeof(LayoutOptions));
		}
	}
}

View on GitHub (pinned to f377ff1c5e)

Solutions

1. Use one of the valid LayoutOptions static field names: Start, Center, End, Fill, StartAndExpand, CenterAndExpand, EndAndExpand, or FillAndExpand.
2. The 'LayoutOptions.' prefix is optional — 'Center' and 'LayoutOptions.Center' are equivalent.
3. Verify the field exists in your MAUI version — some newer layout options may have different names.

Example fix

<!-- before -->
<Label HorizontalOptions="Middle" />

<!-- after -->
<Label HorizontalOptions="Center" />

// Validate a LayoutOptions XAML string against known static fields
static readonly HashSet<string> ValidLayoutOptions = new(StringComparer.OrdinalIgnoreCase)
{
    "Start","Center","End","Fill",
    "StartAndExpand","CenterAndExpand","EndAndExpand","FillAndExpand"
};
static bool IsValidLayoutOptions(string value)
{
    if (string.IsNullOrWhiteSpace(value)) return false;
    var name = value.Trim();
    if (name.StartsWith("LayoutOptions.", StringComparison.OrdinalIgnoreCase))
        name = name["LayoutOptions.".Length..];
    return ValidLayoutOptions.Contains(name);
}

When it happens

Trigger: Setting HorizontalOptions or VerticalOptions to an unrecognized value such as 'Middle' (should be 'Center'), 'Justify', 'Stretch' (should be 'Fill'), or a non-static custom alignment. Valid fields: Start, Center, End, Fill, StartAndExpand, CenterAndExpand, EndAndExpand, FillAndExpand, CenterStart, etc.

Common situations: Confusing LayoutOptions names with CSS or other framework alignment names. Using deprecated/removed members. Using 'AndExpand' suffix incorrectly. The compiled converter only recognizes fields that actually exist on the LayoutOptions type in the referenced MAUI version.

Related errors

• XC0040
• XC0040
• XC0040
• XC0040
• XC0040

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