microsoft/aspire · error · InvalidOperationException

Foundry CLI command ' ' failed with exit code

Error message

Foundry CLI command '{FormatCommand(arguments)}' failed with exit code {result.ExitCode}: {result.Error}{result.Output}

What it means

Aspire's FoundryLocalService shells out to the `foundry` CLI (via RunFoundryCommandAsync) for operations like loading models, checking model status, and starting/stopping the local service. When the CLI process exits with a non-zero exit code, the library wraps the command line, exit code, and captured stderr/stdout in this InvalidOperationException. It means the Foundry CLI itself rejected or failed the requested operation, not that Aspire failed internally.

Solutions

Read the CLI's Error text embedded in the exception message and run the same `foundry ...` command manually in a terminal to see the full failure.
Verify the Foundry Local CLI is installed and current: `foundry --version`; install/update from https://learn.microsoft.com/azure/ai-foundry/foundry-local/
Confirm the model name/alias exists: `foundry model list` and `foundry model search <name>`; fix the model name passed to AddFoundryLocalModel.
Ensure the Foundry local service is running and healthy (`foundry service status`, start it if needed) before the app host loads models.
Check disk space and network access if the failure happens during model download, and re-run the load.

Example fix

// before: model alias typo surfaces as CLI exit-code failure
var foundry = builder.AddFoundryLocal("foundry")
    .AddModel("phi-4-mini-q4-GS", "my-model");

// after: use a valid alias from `foundry model list`
var foundry = builder.AddFoundryLocal("foundry")
    .AddModel("phi-4-mini", "my-model");

Defensive patterns

Strategy: try-catch

Validate before calling

// Before starting the AppHost, verify the CLI and model are usable:
//   foundry --version && foundry model list | grep <modelName>
var psi = new ProcessStartInfo("foundry", $"model list") { RedirectStandardOutput = true, UseShellExecute = false };
using var p = Process.Start(psi)!;
var list = await p.StandardOutput.ReadToEndAsync();
bool modelAvailable = list.Contains("phi-4-mini");

Try / catch

try
{
    await modelResource.WaitForModelReadyAsync(...);
}
catch (InvalidOperationException ex) when (ex.Message.StartsWith("Foundry CLI command"))
{
    logger.LogError(ex, "Foundry CLI failed: {Message}", ex.Message);
    // surface remediation steps (install CLI, fix model name, start service)
}

Prevention

Install and keep the Foundry Local CLI up to date before running the AppHost.
Validate model names against `foundry model list` / `foundry model search` instead of hardcoding guesses.
Run the exact CLI command manually first when a new model or CLI version is involved.
Ensure the Foundry service is running before app-host startup in scripts and CI.

When it happens

Trigger: Any call path that runs a foundry CLI command returns a non-zero exit code: LoadModelAsync (foundry model load), IsModelLoadedAsync (foundry model info), GetModelIdAsync, StartAsync/StartCliServerAsync help/version probes, and StopAsync. The exception message embeds FormatCommand(arguments), the exit code, and the CLI's Error+Output text.

Common situations: The Foundry Local CLI is not installed or an older version lacks the invoked subcommand; the requested model name/alias does not exist locally or in the catalog; the Foundry service/daemon is not running or not accepting requests; the model download failed (disk space, network); or the user is not logged in / lacks entitlement for the model.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Foundry/FoundryLocalService.cs:364

        }
    }

    private static async Task<string> RunFoundryCommandAsync(
        string[] arguments,
        Action<string>? onOutput,
        CancellationToken cancellationToken,
        bool stopReadingAfterProcessExit = false,
        Func<string, bool>? outputCompletionPredicate = null)
    {
        var result = await RunFoundryCommandCoreAsync(
            arguments,
            onOutput,
            cancellationToken,
            stopReadingAfterProcessExit,
            outputCompletionPredicate).ConfigureAwait(false);
        if (result.ExitCode != 0)
        {
            throw new InvalidOperationException($"Foundry CLI command '{FormatCommand(arguments)}' failed with exit code {result.ExitCode}: {result.Error}{result.Output}");
        }

        return result.Output;
    }

    private static async Task<FoundryCommandResult> RunFoundryCommandCoreAsync(
        string[] arguments,
        Action<string>? onOutput,
        CancellationToken cancellationToken,
        bool stopReadingAfterProcessExit = false,
        Func<string, bool>? outputCompletionPredicate = null)
    {
        using var process = new Process
        {
            StartInfo = CreateFoundryStartInfo(arguments)
        };

        return await RunProcessAsync(

View on GitHub (pinned to 25830f84bd)