PrismLibrary/Prism · critical · PrismInitializationException

An error occurred while initializing the Modules.

Error message

An error occurred while initializing the Modules.

What it means

After the module catalog is configured, Prism runs each module's initialization (IModuleManager.Run). If a module's OnInitialized/RegisterTypes throws, Prism logs the error and rethrows it as a PrismInitializationException with this message. The app cannot finish startup.

Solutions

  1. Read the logged error (LogError with 'An error ocurred while initializing the Modules') and the InnerException to identify the failing module.
  2. Wrap or fix the throwing code in the module's Initialize/RegisterTypes; register any missing dependencies before module initialization.
  3. Change the module to InitializationMode.WhenAvailable if it need not initialize at startup.
  4. Test the module in isolation to reproduce and fix the constructor/initialization failure.

Example fix

// before: module Initialize does I/O that throws
public void Initialize(IContainerProvider container) => LoadCacheFromDisk();
// after: guard and defer
public void Initialize(IContainerProvider container)
{
    if (File.Exists(CachePath)) LoadCacheFromDisk();
}
Defensive patterns

Strategy: try-catch

Validate before calling

// Ensure module dependencies resolve before Run
foreach (var m in catalog.Modules)
    container.Resolve(m.ModuleType);

Try / catch

try
{
    moduleManager.Run();
}
catch (PrismInitializationException ex)
{
    logger.LogError(ex.InnerException, "Module init failed");
}

Prevention

When it happens

Trigger: A registered module's IModule.Initialize or RegisterTypes throws during OnInitialized — e.g. resolving a missing service, throwing in module constructor, or module logic that depends on unavailable platform services.

Common situations: Module relying on a service not yet registered; module constructor doing I/O or configuration that fails on device; module registered for the wrong platform; version drift between module and host DI registrations.

Related errors

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

Appendix: source

Thrown at src/Maui/Prism.Maui/PrismAppBuilder.cs:228

        else if (errors.Count > 1)
        {
            throw new AggregateException("One or more errors were encountered while configuring the Module Catalog", [.. errors]);
        }

        // Phase 2: Initialize modules so their services are registered
        if (_container.IsRegistered<IModuleCatalog>() && _container.Resolve<IModuleCatalog>().Modules.Any())
        {
            try
            {
                logger.LogDebug("Initializing modules.");
                var manager = _container.Resolve<IModuleManager>();
                manager.Run();
                logger.LogDebug("Modules Initialized.");
            }
            catch (Exception ex)
            {
                logger.LogError(ex, "An error ocurred while initializing the Modules.");
                throw new PrismInitializationException("An error occurred while initializing the Modules.", ex);
            }
        }
        else
        {
            logger.LogDebug("No Modules found to initialize.");
        }

        // Phase 3: Run OnInitialized delegates (module services are now available)
        _initializations.ForEach(action =>
        {
            try
            {
                action(_container);
            }
            catch (Exception ex)
            {
                logger.LogError(ex, "Error executing Initialization Delegate.");
                errors.Add(ex);

View on GitHub (pinned to 358118cd64)