What causes "underlyingNameScope" in dotnet/wpf?

Create or obtain the actual NameScope/INameScope instance before constructing NameScopeDictionary

dotnet/wpf · error · ArgumentNullException

underlyingNameScope

Error message

underlyingNameScope

What it means

The NameScopeDictionary(INameScope underlyingNameScope) constructor requires an underlying INameScope to delegate name registration to. Passing null leaves the dictionary without its backing scope, so it throws ArgumentNullException via the ?? throw pattern.

Solutions

Create or obtain the actual NameScope/INameScope instance before constructing NameScopeDictionary
Guard the call site so the underlying scope is initialized lazily if it can be null
Pass a default NameScope instance if a real one is unavailable

Example fix

// before
var dict = new NameScopeDictionary(underlyingNameScope); // underlyingNameScope is null
// after
var dict = new NameScopeDictionary(underlyingNameScope ?? new NameScope());

Defensive patterns

Strategy: type-guard

Validate before calling

if (underlyingNameScope is null) throw new InvalidOperationException("Underlying INameScope must be initialized");
var dict = new NameScopeDictionary(underlyingNameScope);

Type guard

static bool CanBuild(INameScope s) => s is not null;

Try / catch

try { var dict = new NameScopeDictionary(scope); }
catch (ArgumentNullException ex) { /* scope was null */ }

Prevention

Initialize the backing NameScope before constructing NameScopeDictionary
Avoid constructing NameScopeDictionary during partial object initialization
Null-check scope dependencies in factory code

When it happens

Trigger: Constructing NameScopeDictionary with a null INameScope argument, typically when a backing NameScope failed to initialize or was passed by mistake.

Common situations: WPF/XAML infrastructure wiring where the underlying NameScope is null because the object is not yet fully initialized; custom code instantiating NameScopeDictionary directly for tests.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of dotnet/wpf@81131a70a4 (2026-09-14). Data as JSON: /api/errors/28bf8aefb3d07fde. Report an issue: GitHub.

Appendix: source

Thrown at src/Microsoft.DotNet.Wpf/src/System.Xaml/System/Xaml/NameScopeDictionary.cs:33

    // of HybridDictionary to match the performance semantics of 3.0 for the time being
    // Note that the IEnumerable<T> uses KeyValuePair<string, object>
    // This means that we need to create KeyValuePairs on the fly
    // The other option would be to just use IEnumerable (or change the HybridDictionary to Dictionary<K,V>)
    // but I opted for generic usability for now since this shouldn't be a common hot path.
    internal class NameScopeDictionary : INameScopeDictionary
    {
        private HybridDictionary _nameMap;
        private INameScope _underlyingNameScope;
        private FrugalObjectList<string> _names;

        public NameScopeDictionary()
        {
        }

        public NameScopeDictionary(INameScope underlyingNameScope)
        {
            _names = new FrugalObjectList<string>();
            _underlyingNameScope = underlyingNameScope ?? throw new ArgumentNullException(nameof(underlyingNameScope));
        }

        public void RegisterName(string name, object scopedElement)
        {
            ArgumentNullException.ThrowIfNull(name);

            ArgumentNullException.ThrowIfNull(scopedElement);

            if (name.Length == 0)
                throw new ArgumentException(SR.NameScopeNameNotEmptyString);

            if (!NameValidationHelper.IsValidIdentifierName(name))
            {
                throw new ArgumentException(SR.Format(SR.NameScopeInvalidIdentifierName, name));
            }

            if (_underlyingNameScope is not null)
            {

View on GitHub (pinned to 81131a70a4)