AvaloniaUI/Avalonia · error · KeyNotFoundException

Could not find control '{name}'.

Error message

Could not find control '{name}'.

What it means

Thrown as a KeyNotFoundException by NameScopeExtensions.Get<T>(INameScope, string) when no element with the given name is registered in the scope. Get<T> (unlike Find<T>) treats a missing name as an error and throws rather than returning null.

Source

Thrown at src/Avalonia.Base/Controls/NameScopeExtensions.cs:79

        /// <summary>
        /// Gets a named element from an <see cref="INameScope"/> or throws if no element of the
        /// requested name was found.
        /// </summary>
        /// <typeparam name="T">The element type.</typeparam>
        /// <param name="nameScope">The name scope.</param>
        /// <param name="name">The name.</param>
        /// <returns>The named element.</returns>
        public static T Get<T>(this INameScope nameScope, string name)
            where T : class
        {
            _ = nameScope ?? throw new ArgumentNullException(nameof(nameScope));
            _ = name ?? throw new ArgumentNullException(nameof(name));

            var result = nameScope.Find(name);

            if (result == null)
            {
                throw new KeyNotFoundException($"Could not find control '{name}'.");
            }

            if (result is T typed)
            {
                return typed;
            }

            throw new InvalidOperationException(
                $"Expected control '{name}' to be '{typeof(T)} but it was '{result.GetType()}'.");
        }

        /// <summary>
        /// Gets a named element from an <see cref="INameScope"/> or throws if no element of the
        /// requested name was found.
        /// </summary>
        /// <typeparam name="T">The element type.</typeparam>
        /// <param name="anchor">The control to take the name scope from.</param>
        /// <param name="name">The name.</param>

View on GitHub (pinned to 11c5427268)

Solutions

1. Use Find<T> instead of Get<T> if the element may legitimately be absent; handle the null return.
2. Verify the x:Name in XAML exactly matches the string passed to Get, including casing.
3. Ensure the template is applied and the correct NameScope is being queried before calling Get.

Example fix

// before
var btn = nameScope.Get<Button>("saveBtn"); // KeyNotFound if misspelled
// after
var btn = nameScope.Find<Button>("saveBtn");
if (btn is null) return; // or handle gracefully

var found = nameScope.Find(name);
if (found is null)
    throw new InvalidOperationException($"'{name}' not registered.");
// proceed, or use Find and handle null gracefully

try { return nameScope.Get<T>(name); }
catch (KeyNotFoundException ex) when (ex.Message.Contains("Could not find"))
{ return null; // or default }

When it happens

Trigger: Calling nameScope.Get<TextBox>("nonExistent") where no element named "nonExistent" is registered. Also fires if Get is called before the template/name scope is populated.

Common situations: Typo in the name string vs the x:Name in XAML. Calling Get before the template has been applied (NameScope not yet populated). Name scope is on a different element than expected (wrong anchor). Refactoring removed a named control but left a Get call.

Related errors

• Control with the name '{name}' already registered.
• Expected control '{name}' to be '{typeof(T)} but it was '{re
• Cannot create ElementName binding when NameScope is null
• No Setter property assigned.
• 'name' may not contain periods.

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