microsoft/aspire · error · InvalidOperationException

Unknown value " ". Valid values are .

Error message

Unknown {typeof(T).Name} value "{value}". Valid values are {string.Join(", ", Enum.GetNames(typeof(T)))}.

What it means

IConfigurationExtensions.GetEnum<T> parses a configuration value into enum type T case-insensitively and throws InvalidOperationException listing the valid enum names when the value does not match any member. The message includes the type name, offending value, and the valid alternatives.

Solutions

Set the config value to one of the names listed in the exception message (case-insensitive)
Use Enum.TryParse or Enum.IsDefined on the raw value before calling GetEnum to validate
Check for typos or stray whitespace in the configuration value
Confirm the value was not written for a different enum type than the generic parameter T
If enum members were renamed in a newer version, migrate the stored config value accordingly

Example fix

// before
// DASHBOARD_MODE=Prodcution   (typo)
var mode = configuration.GetEnum<DashboardMode>("DASHBOARD_MODE"); // throws
// after
// DASHBOARD_MODE=Production
var mode = configuration.GetEnum<DashboardMode>("DASHBOARD_MODE");
// or defensively:
var raw = configuration["DASHBOARD_MODE"];
var mode = Enum.TryParse<DashboardMode>(raw, ignoreCase: true, out var m)
    ? m
    : DashboardMode.Production; // fallback default

Defensive patterns

Strategy: validation

Validate before calling

var raw = configuration[key];
if (!Enum.TryParse<T>(raw, ignoreCase: true, out var parsed))
    throw new InvalidOperationException($"'{key}' must be one of: {string.Join(", ", Enum.GetNames(typeof<T>))}.");

Type guard

static bool IsValidEnumValue<T>(string? raw) where T : struct, Enum =>
    Enum.TryParse<T>(raw, ignoreCase: true, out _);

Try / catch

try { return configuration.GetEnum<T>(key); }
catch (InvalidOperationException ex) { logger.LogError(ex, "Unknown value for '{Key}'; using default", key); return defaultEnumValue; }

Prevention

Copy enum names exactly from the exception's valid-values list
Validate config enums at startup, not deep in request paths
Trim whitespace from hand-edited appsettings values
Update stored config when enum members are renamed between versions

When it happens

Trigger: Calling GetEnum<T>(configuration, key) where the key's value is a non-empty string that is not a valid T member — e.g. a typo, a different casing convention with added characters, a numeric string not corresponding to a defined name parse, or a value written for a different enum type.

Common situations: Config value changed between app versions after enum members were renamed; user hand-edited appsettings with an unsupported word like 'Default ' (trailing space works via parse? — trailing whitespace causes failure); value copied from documentation of another library's enum.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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

Appendix: source

Thrown at src/Shared/IConfigurationExtensions.cs:202

    /// <param name="defaultValue">A default value, for when the configuration value is unable to be parsed.</param>
    /// <exception cref="InvalidOperationException">The configuration value is not a valid member of the enum.</exception>
    /// <returns>The parsed enum member, or <paramref name="defaultValue"/> the configuration value was null or empty.</returns>
    [return: NotNullIfNotNull(nameof(defaultValue))]
    public static T? GetEnum<T>(this IConfiguration configuration, string key, T? defaultValue = default)
        where T : struct
    {
        var value = configuration[key];

        if (value is null or [])
        {
            return defaultValue;
        }
        else if (Enum.TryParse<T>(value, ignoreCase: true, out var e))
        {
            return e;
        }

        throw new InvalidOperationException($"Unknown {typeof(T).Name} value \"{value}\". Valid values are {string.Join(", ", Enum.GetNames(typeof(T)))}.");
    }

    /// <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)

View on GitHub (pinned to 25830f84bd)