PrismLibrary/Prism · error · RegionCreationException

An exception occurred while creating a region with name

Error message

An exception occurred while creating a region with name '{0}'. The exception was: {1}.

What it means

CreateRegion wraps any failure while initializing a region (adapter lookup, adapter.Initialize, container resolution) in a RegionCreationException whose message names the region and the inner exception. It tells you region construction itself failed, with the original cause as InnerException.

Solutions

Read the InnerException to find the real cause
Register a region adapter mapping for the host element type in your PrismAppBuilder configuration (ConfigureRegionAdapterMappings)
Verify the DI container is configured before any region creation
Check for duplicate region names or invalid adapter initialization logic

Example fix

// before
// no adapter for custom host -> RegionCreationException
// after
protected override void ConfigureRegionAdapterMappings(IRegionAdapterMappings regionAdapterMappings)
{
    base.ConfigureRegionAdapterMappings(regionAdapterMappings);
    regionAdapterMappings.RegisterMapping(typeof(MyCustomHost), Container.Resolve<MyHostRegionAdapter>());
}

Defensive patterns

Strategy: try-catch

Validate before calling

if (_regionAdapterMappings.GetMapping(host.GetType()) is null) throw new InvalidOperationException($"No region adapter for {host.GetType().Name}");

Try / catch

try { /* region activation */ }
catch (RegionCreationException ex)
{ logger.Error(ex.InnerException, "Region '{Region}' failed", ex.RegionName); }

Prevention

Register adapters for all custom host types via ConfigureRegionAdapterMappings
Initialize DI container before any region usage
Keep region names unique and valid
Catch RegionCreationException and surface InnerException in diagnostics

When it happens

Trigger: regionAdapterMappings.GetMapping throws for an unregistered element type, or regionAdapter.Initialize fails (e.g. container not yet available, invalid regionName, adapter threw), all inside CreateRegion's try block.

Common situations: Forgot to register an IRegionAdapter for a custom control type; container misconfiguration after App.RegisterServices changes; region name collisions; Maui version upgrades changing VisualElement behavior.

Related errors

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

Appendix: source

Thrown at src/Maui/Prism.Maui/Navigation/Regions/Behaviors/DelayedRegionCreationBehavior.cs:140

        if (targetElement == null)
            throw new ArgumentNullException(nameof(targetElement));

        try
        {
            if (!targetElement.TryGetParentPage(out var page))
                throw new Exception("The Target Element has not yet been parented and we cannot get the parent page.");

            // Build the region
            var container = page.GetContainerProvider();
            targetElement.SetContainerProvider(container);
            var regionAdapter = _regionAdapterMappings.GetMapping(targetElement.GetType());
            var region = regionAdapter.Initialize(targetElement, regionName);

            return region;
        }
        catch (Exception ex)
        {
            throw new RegionCreationException(string.Format(CultureInfo.CurrentCulture, Resources.RegionCreationException, regionName, ex), ex);
        }
    }

    /// <summary>
    /// Add the instance of this class to <see cref="_instanceTracker"/> to keep it alive
    /// </summary>
    private void Track()
    {
        lock (_trackerLock)
        {
            if (!_instanceTracker.Contains(this))
            {
                _instanceTracker.Add(this);
            }
        }
    }

    /// <summary>

View on GitHub (pinned to 358118cd64)