dotnet/maui · error · ArgumentException

Default value did not match return type. Property: {returnTy

Error message

Default value did not match return type. Property: {returnType} {declaringType.Name}.{propertyName} Default value type: {defaultValue.GetType().Name}, 

What it means

ArgumentException thrown by the BindableProperty constructor when the supplied default value is non-null but is not an instance of the declared returnType. The constructor first fills in a default for non-nullable value types via Activator.CreateInstance, then checks assignability here; a mismatch means the property would carry a value of the wrong type, so it fails fast with the property identity and the actual default-value type.

Source

Thrown at src/Controls/src/Core/BindableProperty.cs:209

		{
			if (propertyName == null)
				throw new ArgumentNullException(nameof(propertyName));
			if (returnType is null)
				throw new ArgumentNullException(nameof(returnType));
			if (declaringType is null)
				throw new ArgumentNullException(nameof(declaringType));
			
			InternalId = Interlocked.Increment(ref _nextInternalId);

			// don't use Enum.IsDefined as its redonkulously expensive for what it does
			if (defaultBindingMode != BindingMode.Default && defaultBindingMode != BindingMode.OneWay && defaultBindingMode != BindingMode.OneWayToSource && defaultBindingMode != BindingMode.TwoWay && defaultBindingMode != BindingMode.OneTime)
				throw new ArgumentException($"Not a valid type of BindingMode. Property: {returnType} {declaringType.Name}.{propertyName}. Default binding mode: {defaultBindingMode}", nameof(defaultBindingMode));

			if (defaultValue == null && Nullable.GetUnderlyingType(returnType) == null && returnType.IsValueType)
				defaultValue = Activator.CreateInstance(returnType);

			if (defaultValue != null && !returnType.IsInstanceOfType(defaultValue))
				throw new ArgumentException($"Default value did not match return type. Property: {returnType} {declaringType.Name}.{propertyName} Default value type: {defaultValue.GetType().Name}, ", nameof(defaultValue));

			if (defaultBindingMode == BindingMode.Default)
				defaultBindingMode = BindingMode.OneWay;

			PropertyName = propertyName;
			ReturnType = returnType;
			DeclaringType = declaringType;
			DefaultValue = defaultValue;
			DefaultBindingMode = defaultBindingMode;
			PropertyChanged = propertyChanged;
			PropertyChanging = propertyChanging;
			ValidateValue = validateValue;
			CoerceValue = coerceValue;
			BindingChanging = bindingChanging;
			IsReadOnly = isReadOnly;
			DefaultValueCreator = defaultValueCreator;
		}

View on GitHub (pinned to f377ff1c5e)

Solutions

1. Make the default value's runtime type assignable to returnType (e.g. pass 0, not "0", for an int).
2. If returnType changed, update every Create call site's default literal.
3. For nullable value types pass null rather than a typed default.

Example fix

// before
public static readonly BindableProperty CountProperty =
    BindableProperty.Create(nameof(Count), typeof(int), typeof(V), "0");

// after
public static readonly BindableProperty CountProperty =
    BindableProperty.Create(nameof(Count), typeof(int), typeof(V), 0);

if (defaultValue is not null && !returnType.IsInstanceOfType(defaultValue))
    throw new ArgumentException("default value type mismatch", nameof(defaultValue));
var bp = BindableProperty.Create(nameof(X), returnType, typeof(V), defaultValue);

static bool DefaultMatches(Type returnType, object defaultValue) =>
    defaultValue is null || returnType.IsInstanceOfType(defaultValue);

When it happens

Trigger: BindableProperty.Create(nameof(X), typeof(int), typeof(V), "0") (string default for an int property); Create(typeof(Color), typeof(V), Brushes.Red) where the value is a related but distinct type; passing an enum value when returnType is the underlying int.

Common situations: Changing a property's returnType after authoring defaults; XAML/compiled defaults where the literal type doesn't match; box/unbox mismatches with nullable value types.

Related errors

• propertyName
• returnType
• declaringType
• Not a valid type of BindingMode. Property: {returnType} {dec
• New element must be a CarouselPage

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