AvaloniaUI/Avalonia · error · ArgumentException

Control with the name '{name}' already registered.

Error message

Control with the name '{name}' already registered.

What it means

Thrown by NameScope.Register when a different element is already registered under the same name in the same NameScope. Registering the identical element reference twice is allowed (idempotent), but registering two distinct objects under one name violates XAML name uniqueness and is rejected.

Source

Thrown at src/Avalonia.Base/Controls/NameScope.cs:65

            _ = styled ?? throw new ArgumentNullException(nameof(styled));

            styled.SetValue(NameScopeProperty, value);
        }

        /// <inheritdoc />
        public void Register(string name, object element)
        {
            if (IsCompleted)
                throw new InvalidOperationException("NameScope is completed, no further registrations are allowed");

            _ = name ?? throw new ArgumentNullException(nameof(name));
            _ = element ?? throw new ArgumentNullException(nameof(element));

            if (_inner.TryGetValue(name, out var existing))
            {
                if (existing != element)
                {
                    throw new ArgumentException($"Control with the name '{name}' already registered.");
                }
            }
            else
            {
                _inner.Add(name, element);
                if (_pendingSearches.Remove(name, out var tcs))
                {
                    tcs.SetResult(element);
                }
            }
        }

        public SynchronousCompletionAsyncResult<object?> FindAsync(string name)
        {
            var found = Find(name);
            if (found != null)
                return new SynchronousCompletionAsyncResult<object?>(found);
            if (IsCompleted)

View on GitHub (pinned to 11c5427268)

Solutions

1. Ensure every x:Name in a single NameScope (template/file) is unique.
2. Before programmatic Register, check scope.Find(name) and either skip or remove the old entry if appropriate.
3. If the collision is intentional (replacement), use a new NameScope rather than reusing the populated one.

Example fix

// before
scope.Register("item", controlA);
scope.Register("item", controlB); // throws
// after
if (scope.Find("item") is null)
    scope.Register("item", controlB);

if (nameScope.Find(name) is null)
    nameScope.Register(name, element);
else if (nameScope.Find(name) != element)
    throw new InvalidOperationException($"Name '{name}' is taken by a different element.");

try { nameScope.Register(name, element); }
catch (ArgumentException ex) when (ex.Message.Contains("already registered"))
{
    // pick a unique name or reuse the existing element
}

When it happens

Trigger: Calling nameScope.Register("myName", elementB) when nameScope already contains elementA != elementB under "myName". Common with two controls sharing x:Name in the same template, or programmatic registration of a duplicate key.

Common situations: Two controls in the same XAML file/template share the same x:Name. Programmatic creation adds a named control whose name collides with a template-defined peer. Copy/paste of XAML without renaming. Shared DataTemplate reused in a context that double-registers.

Related errors

• Expected control '{name}' to be '{typeof(T)} but it was '{re
• NameScope is completed, no further registrations are allowed
• Could not find control '{name}'.
• The control doesn't have an associated name scope, probably
• Cannot create ElementName binding when NameScope is null

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