OrchardCMS/OrchardCore · critical · InvalidOperationException

The 'OrchardCore.Shells.Database' configuration section…

Error message

The 'OrchardCore.Shells.Database' configuration section should define a 'DatabaseProvider'

What it means

The Database Shells storage feature requires a database provider to know which database engine stores shell configuration. When the 'OrchardCore.Shells.Database' configuration section exists but omits the 'DatabaseProvider' key, GetDatabaseContextAsync cannot construct a shell context and throws immediately. This is a fail-fast guard against an incomplete storage configuration.

Solutions

1. Add 'DatabaseProvider' under the 'OrchardCore.Shells.Database' configuration section (e.g. "Sqlite", "SqlServer", "MySql", "Postgres").
2. Ensure the matching database provider feature/package is referenced so the provider name resolves.
3. Supply the value via environment variable, e.g. OrchardCore__Shells__Database__DatabaseProvider, in containerized deployments.
4. Verify the loaded configuration at startup (log options.DatabaseProvider) to catch binding issues such as casing or missing section.

Example fix

// before (appsettings.json)
"OrchardCore.Shells.Database": {
  "ConnectionString": "...",
  "TablePrefix": "Shell_"
}
// after
"OrchardCore.Shells.Database": {
  "DatabaseProvider": "Sqlite",
  "ConnectionString": "...",
  "TablePrefix": "Shell_"
}

var section = config.GetSection("OrchardCore.Shells.Database");
if (section.Exists() && string.IsNullOrEmpty(section["DatabaseProvider"]))
    throw new InvalidOperationException("OrchardCore.Shells.Database requires DatabaseProvider");

When it happens

Trigger: Running the app with shells storage backed by the database while appsettings.json (or env vars) has an 'OrchardCore.Shells.Database' section lacking 'DatabaseProvider', e.g. only connection string or table prefix configured.

Common situations: Copying a partial config snippet from docs, renaming config keys during upgrades, deploying without environment-variable overrides for DatabaseProvider, or setting up database-based shell storage for the first time.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• The configured table name separator
• The configured identity column size
• Unknown database provider:
• A feature is missing a mandatory 'Id' property in the Module
• Unsupported database provider

AI-assisted analysis of OrchardCMS/OrchardCore@4306c0717f (2026-09-13). Data as JSON: /api/errors/ac0a49ec8824c6af. Report an issue: GitHub.

Appendix: source

Thrown at src/OrchardCore/OrchardCore.Infrastructure/Shells.Database/Extensions/DatabaseShellContextFactoryExtensions.cs:15

using OrchardCore.Environment.Shell;
using OrchardCore.Environment.Shell.Builders;
using OrchardCore.Environment.Shell.Descriptor.Models;
using OrchardCore.Shells.Database.Configuration;

namespace OrchardCore.Shells.Database.Extensions;

public static class DatabaseShellContextFactoryExtensions
{
    internal static Task<ShellContext> GetDatabaseContextAsync(
        this IShellContextFactory shellContextFactory, DatabaseShellsStorageOptions options)
    {
        if (options.DatabaseProvider is null)
        {
            throw new InvalidOperationException("The 'OrchardCore.Shells.Database' configuration section should define a 'DatabaseProvider'");
        }

        var settings = new ShellSettings()
            .AsDefaultShell()
            .AsDisposable()
            .AsRunning();

        settings["DatabaseProvider"] = options.DatabaseProvider;
        settings["ConnectionString"] = options.ConnectionString;
        settings["TablePrefix"] = options.TablePrefix;
        settings["Schema"] = options.Schema;

        return shellContextFactory.CreateDescribedContextAsync(settings, new ShellDescriptor());
    }
}

View on GitHub (pinned to 4306c0717f)