abpframework/abp · critical · AbpInitializationException

An error occurred during PreConfigureServices phase of the m

Error message

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

What it means

The synchronous counterpart of error 241. ABP iterates every module implementing IPreConfigureServices and calls PreConfigureServices(context) - the earliest sync lifecycle phase. If any module throws, ABP wraps it in AbpInitializationException naming the module's AssemblyQualifiedName with the original as InnerException. The real cause is always the inner exception.

Source

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

        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
            {
                ((IPreConfigureServices)module.Instance).PreConfigureServices(context);
            }
            catch (Exception ex)
            {
                throw new AbpInitializationException($"An error occurred during {nameof(IPreConfigureServices.PreConfigureServices)} 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 source line live there.
Open the PreConfigureServices override of the module named in the message.
Verify the configuration section or connection string the module reads at pre-configure time is present and well-formed.

Defensive patterns

Strategy: try-catch

Try / catch

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

Prevention

Log and read ex.InnerException - the wrapper hides the real cause.
Unit-test each module's PreConfigureServices with the real IConfiguration.
Pre-validate required config sections before startup.

When it happens

Trigger: A module's PreConfigureServices override throws: bad config binding, null reference reading settings, or registering something that errors.

Common situations: Typo in an appsettings.json key read at pre-configure; ABP version mismatch; a connection string referenced in PreConfigureServices that is absent; environment-specific config not loaded.

Related errors

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