abpframework/abp · critical · AbpInitializationException

An error occurred during PreConfigureServicesAsync phase of

Error message

An error occurred during PreConfigureServicesAsync phase of the module {module.Type.AssemblyQualifiedName}. See the inner exception for details.

What it means

During async module initialization ABP iterates every module implementing IPreConfigureServices and awaits PreConfigureServicesAsync(context). Pre-configuration is the earliest lifecycle phase, running before ConfigureServices, so it is the first place module setup can fail. If any module throws, ABP wraps the exception in AbpInitializationException naming the offending module's AssemblyQualifiedName and preserving the original as InnerException - the real cause is always one level down.

Source

Thrown at framework/src/Volo.Abp.Core/Volo/Abp/AbpApplicationBase.cs:242

        foreach (var module in Modules)
        {
            if (module.Instance is AbpModule abpModule)
            {
                abpModule.ServiceConfigurationContext = context;
            }
        }

        //PreConfigureServices
        foreach (var module in Modules.Where(m => m.Instance is IPreConfigureServices))
        {
            try
            {
                await ((IPreConfigureServices)module.Instance).PreConfigureServicesAsync(context);
            }
            catch (Exception ex)
            {
                throw new AbpInitializationException($"An error occurred during {nameof(IPreConfigureServices.PreConfigureServicesAsync)} phase of the module {module.Type.AssemblyQualifiedName}. See the inner exception for details.", ex);
            }
        }

        var assemblies = new HashSet<Assembly>();

        //ConfigureServices
        foreach (var module in Modules)
        {
            if (module.Instance is AbpModule abpModule)
            {
                if (!abpModule.SkipAutoServiceRegistration)
                {
                    foreach (var assembly in module.AllAssemblies)
                    {
                        if (!assemblies.Contains(assembly))
                        {
                            Services.AddAssembly(assembly);
                            assemblies.Add(assembly);

View on GitHub (pinned to 7ed43b1931)

Solutions

Inspect ex.InnerException and its stack trace - the true exception and offending source line live there, not in the wrapper.
Identify the module named by AssemblyQualifiedName in the message and open its PreConfigureServicesAsync override.
Verify the configuration section, connection string, or option the module reads at pre-configure time is present and well-formed.
Reproduce with verbose logging enabled to capture the inner exception detail before the wrapper is thrown.

Defensive patterns

Strategy: try-catch

Try / catch

try
{
    await application.ConfigureServicesAsync();
}
catch (AbpInitializationException ex) when (ex.Message.Contains("PreConfigureServicesAsync"))
{
    startupLogger.LogError(ex.InnerException, "PreConfigure failed in {Module}", ex.Message);
    throw;
}

Prevention

Log and surface ex.InnerException - the wrapper message alone hides the real cause.
Unit-test each module's PreConfigureServicesAsync with the real IConfiguration to catch binding errors before startup.
Validate required configuration sections in a pre-startup health check so missing keys fail loudly before PreConfigure runs.

When it happens

Trigger: A module's PreConfigureServicesAsync override throws: bad configuration binding, a null reference while reading settings, calling Configure<T>() on a missing section, or registering a dependency that itself errors.

Common situations: Typo in an appsettings.json key the module reads at pre-configure time; version mismatch where the module expects a newer ABP API; a connection string referenced in PreConfigureServices that is absent; environment-specific config not loaded in a new deployment.

Related errors

AI-assisted analysis of abpframework/abp@7ed43b1931 (2026-08-13). Data as JSON: /api/errors/75435baefc6ed845. Report an issue: GitHub.