PrismLibrary/Prism · error · KeyNotFoundException

The IRegionAdapter for the type

Error message

The IRegionAdapter for the type {0} is not registered in the region adapter mappings. You can register an IRegionAdapter for this control by overriding the ConfigureRegionAdapterMappings method in the bootstrapper.

What it means

RegionAdapterMappings.GetMapping walks the control type hierarchy looking for a registered IRegionAdapter and throws KeyNotFoundException (Resources.NoRegionAdapterException) when neither the type nor any base type has a mapping. Prism cannot adapt a region on a control it has no adapter for.

Solutions

  1. Override ConfigureRegionAdapterMappings in your PrismApp and register an adapter for the control type (or one of its base types)
  2. Write a custom IRegionAdapter for the third-party/custom control and register it via RegisterMapping<TControl, TAdapter>
  3. Host the control's region inside a mapped container (e.g. put region content in a ContentPresenter/ScrollView that Prism maps)
  4. Verify the control type you registered matches the actual runtime type of the control

Example fix

// before
// MyCustomControl used with RegionManager.RegionName, no adapter

// after
protected override void ConfigureRegionAdapterMappings(IRegionAdapterMappings regionAdapterMappings)
{
    base.ConfigureRegionAdapterMappings(regionAdapterMappings);
    regionAdapterMappings.RegisterMapping<MyCustomControl, MyCustomControlRegionAdapter>();
}
Defensive patterns

Strategy: validation

Validate before calling

bool mapped = mappings is not null; // no public lookup; instead ensure registration in ConfigureRegionAdapterMappings
// Recommended: register before any view with RegionManager.RegionName loads

Try / catch

try { var adapter = mappings.GetMapping(control.GetType()); }
catch (KeyNotFoundException) { /* no adapter for this control type — register one */ }

Prevention

When it happens

Trigger: Marking a control (e.g. a custom ContentView subclass or a third-party control) with RegionManager.RegionName when no adapter is registered for that type or its ancestors; calling GetMapping directly for an unmapped type.

Common situations: Using a third-party or custom control as a region without registering a custom IRegionAdapter; forgetting to override ConfigureRegionAdapterMappings; MAUI upgrades introducing a new control type Prism does not map by default.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

AI-assisted analysis of PrismLibrary/Prism@358118cd64 (2026-09-15). Data as JSON: /api/errors/b4e426718cedab7f. Report an issue: GitHub.

Appendix: source

Thrown at src/Maui/Prism.Maui/Navigation/Regions/Adapters/RegionAdapterMappings.cs:83

    /// <returns>The <see cref="IRegionAdapter"/> mapped to the <paramref name="controlType"/>.</returns>
    /// <remarks>This class will look for a registered type for <paramref name="controlType"/> and if there is not any,
    /// it will look for a registered type for any of its ancestors in the class hierarchy.
    /// If there is no registered type for <paramref name="controlType"/> or any of its ancestors,
    /// an exception will be thrown.</remarks>
    /// <exception cref="KeyNotFoundException">When there is no registered type for <paramref name="controlType"/> or any of its ancestors.</exception>
    public IRegionAdapter GetMapping(Type controlType)
    {
        Type currentType = controlType;

        while (currentType != null)
        {
            if (mappings.TryGetValue(currentType, out IRegionAdapter value))
            {
                return value;
            }
            currentType = currentType.BaseType;
        }
        throw new KeyNotFoundException(string.Format(CultureInfo.CurrentCulture, Resources.NoRegionAdapterException, controlType));
    }

    /// <summary>
    /// Returns the adapter associated with the type provided.
    /// </summary>
    /// <typeparam name="T">The control type used to obtain the <see cref="IRegionAdapter"/> mapped.</typeparam>
    /// <returns>The <see cref="IRegionAdapter"/> mapped to the <typeparamref name="T"/>.</returns>
    /// <remarks>This class will look for a registered type for <typeparamref name="T"/> and if there is not any,
    /// it will look for a registered type for any of its ancestors in the class hierarchy.
    /// If there is no registered type for <typeparamref name="T"/> or any of its ancestors,
    /// an exception will be thrown.</remarks>
    /// <exception cref="KeyNotFoundException">When there is no registered type for <typeparamref name="T"/> or any of its ancestors.</exception>
    public IRegionAdapter GetMapping<T>()
    {
        return GetMapping(typeof(T));
    }
}

View on GitHub (pinned to 358118cd64)