microsoft/aspire · critical · DistributedApplicationException

Invalid operation specified. Valid operations are…

Error message

Invalid operation specified. Valid operations are 'publish', 'run', or 'inspect'.

What it means

DistributedApplicationBuilder reads the AppHost operation mode from the configuration key 'AppHost:Operation' and only accepts 'run', 'publish', or 'inspect' (case-insensitive). Any other or unrecognized value means the host cannot determine whether it should run the app or produce a publish manifest/inspection output, so it fails fast with a DistributedApplicationException.

Solutions

Set AppHost:Operation to exactly 'run', 'publish', or 'inspect' in configuration/environment (e.g. DOTNET_ or appsettings key AppHost__Operation).
Run the AppHost through the standard tooling (aspire run / dotnet run / dotnet publish) instead of executing the binary directly, so the operation is configured automatically.
Fix typos and casing-neutral values; the comparison is ToLowerInvariant, so 'RUN' works but 'RunMode' does not.

Example fix

// before (appsettings.json / env)
"AppHost": { "Operation": "deploy" }
// after
"AppHost": { "Operation": "publish" }

Defensive patterns

Strategy: validation

Validate before calling

var op = builder.Configuration["AppHost:Operation"]?.ToLowerInvariant();
if (op is not ("run" or "publish" or "inspect"))
    throw new InvalidOperationException($"AppHost:Operation '{op}' is invalid; use run, publish, or inspect.");

Try / catch

try { var app = builder.Build(); } catch (DistributedApplicationException ex) when (ex.Message.Contains("Invalid operation specified")) { /* log config key AppHost:Operation and correct it */ }

Prevention

Only set AppHost:Operation through the standard aspire tooling.
Whitelist-validate any code that sets the operation key programmatically.
Use constants instead of raw strings for the operation value.

When it happens

Trigger: Configuration key AppHost:Operation is set to an unrecognized value (e.g. 'Run ' as written via a custom host, 'debug', 'deploy'), or the key is absent in a context where the builder expects it to be set by dotnet run/publish infrastructure.

Common situations: Custom AppHost launch setups or test harnesses that set DistributedApplicationOptions/operation via environment variables or appsettings with a typo; invoking the AppHost executable directly without the tooling that normally sets AppHost:Operation; older tooling versions writing a value like 'generate' that the current SDK no longer accepts.

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/b10b173bd5f5dd27. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting/DistributedApplicationBuilder.cs:155

    private readonly DistributedApplicationExecutionContextOptions _executionContextOptions;

    private DistributedApplicationExecutionContextOptions BuildExecutionContextOptions()
    {
        var operationConfiguration = _innerBuilder.Configuration["AppHost:Operation"];
        if (operationConfiguration is null)
        {
            return _innerBuilder.Configuration["Publishing:Publisher"] switch
            {
                { } publisher => new DistributedApplicationExecutionContextOptions(DistributedApplicationOperation.Publish, publisher),
                _ => new DistributedApplicationExecutionContextOptions(DistributedApplicationOperation.Run) { RunConfiguration = BuildRunConfiguration() }
            };
        }

        return _innerBuilder.Configuration["AppHost:Operation"]?.ToLowerInvariant() switch
        {
            "run" => new DistributedApplicationExecutionContextOptions(DistributedApplicationOperation.Run) { RunConfiguration = BuildRunConfiguration() },
            "publish" or "inspect" => new DistributedApplicationExecutionContextOptions(DistributedApplicationOperation.Publish, _innerBuilder.Configuration["Publishing:Publisher"] ?? "manifest"),
            _ => throw new DistributedApplicationException("Invalid operation specified. Valid operations are 'publish', 'run', or 'inspect'.")
        };
    }

    private RunConfiguration BuildRunConfiguration()
    {
        // Only "true" and "false" (case-insensitively) are accepted. bool.TryParse rejects everything else,
        // including values some configuration sources emit for booleans such as "1" or "yes". An unusable
        // value must never fail an otherwise valid run, so anything unrecognized falls back to the default.
        return new RunConfiguration
        {
            WatchEnabled = bool.TryParse(_innerBuilder.Configuration["AppHost:Run:WatchEnabled"], out var watchEnabled) && watchEnabled
        };
    }

    /// <summary>
    /// Initializes a new instance of the <see cref="DistributedApplicationBuilder"/> class with the specified options.
    /// </summary>
    /// <param name="options">The options for the distributed application.</param>

View on GitHub (pinned to 25830f84bd)