AvaloniaUI/Avalonia · error · ArgumentException

'name' may not contain periods.

Error message

'name' may not contain periods.

What it means

Thrown by the AvaloniaProperty constructor when the registered name contains a '.' (period). Periods are reserved because Avalonia uses 'Owner.Property' syntax to reference attached properties in XAML and bindings, so a dotted name would create parsing ambiguity.

Source

Thrown at src/Avalonia.Base/AvaloniaProperty.cs:62

        /// <param name="hostType">The class that the property being is registered on.</param>
        /// <param name="metadata">The property metadata.</param>
        /// <param name="notifying">A <see cref="Notifying"/> callback.</param>
        private protected AvaloniaProperty(
            string name,
            Type valueType,
            Type ownerType,
            Type hostType,
            AvaloniaPropertyMetadata metadata,
            Action<AvaloniaObject, bool>? notifying = null)
        {
            ThrowHelper.ThrowIfNull(name, nameof(name));
            ThrowHelper.ThrowIfNull(valueType, nameof(valueType));
            ThrowHelper.ThrowIfNull(ownerType, nameof(ownerType));
            ThrowHelper.ThrowIfNull(metadata, nameof(metadata));

            if (name.Contains('.'))
            {
                throw new ArgumentException("'name' may not contain periods.");
            }

            Name = name;
            PropertyType = valueType;
            OwnerType = ownerType;
            Notifying = notifying;
            Id = s_nextId++;

            metadata.Freeze();
            _metadata.Add(hostType, metadata);
            _defaultMetadata = metadata.GenerateTypeSafeMetadata();
            _singleHostType = hostType;
            _singleMetadata = metadata;
        }

        /// <summary>
        /// Initializes a new instance of the <see cref="AvaloniaProperty"/> class.
        /// </summary>

View on GitHub (pinned to 11c5427268)

Solutions

1. Pass only the unqualified member name (e.g. 'Left' for DockPanel.Left).
2. Strip the owner prefix before registering.
3. For attached properties the owner association is handled by RegisterAttached's owner type parameter, not by the name.

Example fix

// before
AvaloniaProperty.Register<Grid, int>("Grid.Row", ...);

// after
AvaloniaProperty.Register<Grid, int>("Row", ...);

if (name.Contains('.'))
    name = name.Substring(name.LastIndexOf('.') + 1);

static bool IsValidPropertyName(string name) =>
    !string.IsNullOrWhiteSpace(name) && !name.Contains('.');

When it happens

Trigger: Calling AvaloniaProperty.Register/RegisterAttached/RegisterDirect with a name argument like 'Foo.Bar'; programmatically building a property name that includes the owner prefix.

Common situations: Copy-pasting the 'Owner.Member' qualified name from XAML into the Register name argument; code generators emitting fully-qualified names.

Related errors

• The property {property.Name} is readonly.
• Invalid priority ${priority}
• Property '{property.Name} not registered on '{o.GetType()}
• Cannot register a non-attached property as attached.
• Transition elements have different parents.

AI-assisted analysis of AvaloniaUI/Avalonia@11c5427268 (2026-08-13). Data as JSON: /api/errors/d681212f4e5d7c88. Report an issue: GitHub.