microsoft/aspire · error · InvalidOperationException

Missing required configuration for

Error message

Missing required configuration for {key}. Valid values are {string.Join(", ", Enum.GetNames(typeof(T)))}.

What it means

IConfiguration.GetEnum<T>(key) is the required-value overload: it reads the configuration key and throws InvalidOperationException when the key is absent or empty, because a required enum setting could not be resolved. The message lists every valid enum member name so the developer knows what to set. Parsing itself (in the optional overload) is case-insensitive via Enum.TryParse.

Solutions

Add the missing key to your configuration (appsettings.json, environment variable, or user secrets) with a valid enum member name, e.g. "SomeKey": "ValidValue".
Verify the key spelling matches the key passed to GetEnum<T>.
If the value should be optional, call the overload with a default: configuration.GetEnum<T>(key, defaultValue: SomeEnum.Default).
Confirm the configuration source (JSON file, env vars) is actually loaded into the IConfiguration built at startup.

Example fix

// before (appsettings.json missing the key)
{ }
var mode = config.GetEnum<CacheMode>("Cache:Mode");

// after
{ "Cache": { "Mode": "Distributed" } }
var mode = config.GetEnum<CacheMode>("Cache:Mode");

Defensive patterns

Strategy: validation

Validate before calling

var raw = config["Cache:Mode"];
if (string.IsNullOrWhiteSpace(raw))
    throw new InvalidOperationException("Cache:Mode is required. Set it to one of: " + string.Join(", ", Enum.GetNames<CacheMode>()));

Try / catch

try { var mode = config.GetEnum<CacheMode>("Cache:Mode"); }
catch (InvalidOperationException ex) { logger.LogError(ex, "Missing/invalid enum config"); throw; }

Prevention

Validate all required config keys at startup before serving traffic.
Use a strongly typed options class bound at startup so missing keys fail fast in one place.
Keep appsettings.json, user secrets, and env vars in sync across environments.

When it happens

Trigger: Calling configuration.GetEnum<T>("SomeKey") (no defaultValue) where the key is missing from appsettings.json/environment variables/user secrets, or where the value is an empty string.

Common situations: Deploying to an environment where appsettings.json or the expected environment variable was not copied; renaming a config key in code without updating configuration files; forgetting user secrets locally; CI/container images missing the settings file.

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

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/ece163f0a9fb70ed. Report an issue: GitHub.

Appendix: source

Thrown at src/Shared/IConfigurationExtensions.cs:222

    /// <summary>
    /// Gets the specified required configuration value as a member of an enum.
    /// </summary>
    /// <remarks>
    /// Parsing is case-insensitive.
    /// </remarks>
    /// <param name="configuration">The <see cref="IConfiguration"/> this method extends.</param>
    /// <param name="key">The configuration key.</param>
    /// <exception cref="InvalidOperationException">The configuration value is empty or not a valid member of the enum.</exception>
    /// <returns>The parsed enum member.</returns>
    public static T GetEnum<T>(this IConfiguration configuration, string key)
        where T : struct
    {
        var value = configuration.GetEnum<T>(key, defaultValue: null);

        if (value is null)
        {
            throw new InvalidOperationException($"Missing required configuration for {key}. Valid values are {string.Join(", ", Enum.GetNames(typeof(T)))}.");
        }

        return value.Value;
    }

    /// <summary>
    /// Gets a configuration value with support for dash-to-underscore normalization.
    /// First tries the exact configuration key, then tries with dashes replaced by underscores.
    /// </summary>
    /// <remarks>
    /// This supports command-line arguments and environment variables where dashes are replaced with underscores.
    /// For example, a parameter named "my-param" can be resolved from configuration key "my_param".
    /// </remarks>
    /// <param name="configuration">The <see cref="IConfiguration"/> this method extends.</param>
    /// <param name="configKey">The configuration key to look up.</param>
    /// <returns>The configuration value, or <see langword="null"/> if not found.</returns>
    public static string? GetValueWithNormalizedKey(this IConfiguration configuration, string configKey)
    {

View on GitHub (pinned to 25830f84bd)