PrismLibrary/Prism · error · Exception

The builder does not implement IRegistryAware

Error message

The builder does not implement IRegistryAware

What it means

GetNavigationKey requires the passed builder object to implement IRegistryAware so it can look up the ViewModel's navigation key in the view registry. If a custom/foreign INavigationBuilder implementation is passed that lacks the registry, Prism throws a plain Exception: 'The builder does not implement IRegistryAware'.

Solutions

1. Make the custom builder implement IRegistryAware and expose the IViewRegistry (e.g. hold a reference to the app's registry).
2. Use Prism's built-in NavigationBuilder (from navigationService.CreateBuilder()) instead of a custom implementation.
3. In tests, replace the mock with a spy on INavigationService rather than a bespoke INavigationBuilder.

Example fix

// before
class TestBuilder : INavigationBuilder { ... } // no IRegistryAware
// after
class TestBuilder : INavigationBuilder, IRegistryAware
{
    public IViewRegistry Registry { get; }
    public TestBuilder(IViewRegistry registry) => Registry = registry;
    ...
}

if (builder is not IRegistryAware)
    throw new ArgumentException("Builder must implement IRegistryAware to resolve ViewModel navigation keys.");

INavigationBuilder EnsureRegistryAware(INavigationBuilder b) =>
    b is IRegistryAware ? b : throw new ArgumentException("Builder is not IRegistryAware");

try
{
    navigationService.CreateBuilder<MyViewModel>().NavigateAsync();
}
catch (Exception ex) when (ex.Message.Contains("IRegistryAware"))
{
    logger.LogError(ex, "Custom builder lacks IRegistryAware; use Prism's built-in builder");
}

When it happens

Trigger: Calling the generic NavigationBuilderExtensions (CreateBuilder<TViewModel> etc.) with a custom class implementing INavigationBuilder (or ICreateSegmentBuilder etc.) that does not also implement IRegistryAware.

Common situations: Custom navigation builder implementations written for testing or decoration; mock builders in unit tests passed into extension methods; library upgrades where the registry-aware interface was introduced and custom builders weren't updated.

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

• The builder does not implement IRegistryAware
• Cannot destroy .
• The page type ' ' is not supported.
• Unable to determine the current page.
• Value cannot be null. (Parameter 'view')

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

Appendix: source

Thrown at src/Maui/Prism.Maui/Navigation/Builder/NavigationBuilderExtensions.cs:24

public static class NavigationBuilderExtensions
{
    /// <summary>
    /// Creates a <see cref="INavigationBuilder"/> using the current instance of the <see cref="INavigationService"/>.
    /// </summary>
    /// <param name="navigationService">The <see cref="INavigationService"/>.</param>
    /// <returns><see cref="INavigationBuilder"/></returns>
    public static INavigationBuilder CreateBuilder(this INavigationService navigationService) =>
           new NavigationBuilder(navigationService);

    internal static string GetNavigationKey<TViewModel>(object builder)
    {
        var vmType = typeof(TViewModel);
        if (vmType.IsAssignableFrom(typeof(VisualElement)))
            throw new NavigationException(NavigationException.MvvmPatternBreak, typeof(TViewModel).Name);

        if (builder is not IRegistryAware registryAware)
            throw new Exception("The builder does not implement IRegistryAware");

        return registryAware.Registry.GetViewModelNavigationKey(vmType);
    }

    public static INavigationBuilder RelativeBack(this INavigationBuilder builder) =>
        builder.AddSegment("..");

    /// <summary>
    /// This will force the generated Navigation URI to return an Absolute URI resetting the current <see cref="Window"/>'s <see cref="Page"/> property.
    /// </summary>
    /// <param name="builder">The <see cref="INavigationBuilder"/>.</param>
    /// <returns>The <see cref="INavigationBuilder"/>.</returns>
    public static INavigationBuilder UseAbsoluteNavigation(this INavigationBuilder builder) =>
        builder.UseAbsoluteNavigation(true);

    /// <summary>
    /// Adds the specified segment `ViewA` to the Navigation URI
    /// </summary>

View on GitHub (pinned to 358118cd64)