{"record":{"id":"7e0c3051d15e9fb7","repo":"microsoft/aspire","slug":"foundry-cli-command-command-could-not-be-started","errorCode":null,"errorMessage":"Foundry CLI command '{command}' could not be started.","messagePattern":"Foundry CLI command '(.+?)' could not be started\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting.Foundry/FoundryLocalService.cs","lineNumber":401,"sourceCode":"            process,\n            FormatCommand(arguments),\n            onOutput,\n            cancellationToken,\n            stopReadingAfterProcessExit,\n            outputCompletionPredicate).ConfigureAwait(false);\n    }\n\n    internal static async Task<FoundryCommandResult> RunProcessAsync(\n        Process process,\n        string command,\n        Action<string>? onOutput,\n        CancellationToken cancellationToken,\n        bool stopReadingAfterProcessExit = false,\n        Func<string, bool>? outputCompletionPredicate = null)\n    {\n        if (!process.Start())\n        {\n            throw new InvalidOperationException($\"Foundry CLI command '{command}' could not be started.\");\n        }\n\n        using var cancellationRegistration = cancellationToken.Register(static state => KillProcess((Process)state!), process);\n        using var readCancellation = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);\n        var outputCompletionSource = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);\n\n        void ProcessOutput(string line)\n        {\n            onOutput?.Invoke(line);\n            if (outputCompletionPredicate?.Invoke(line) is true)\n            {\n                outputCompletionSource.TrySetResult();\n            }\n        }\n\n        // Read both streams concurrently to avoid deadlock when a pipe buffer fills.\n        var outputTask = ReadOutputAsync(process.StandardOutput, ProcessOutput, cancellationToken, readCancellation.Token);\n        var errorTask = ReadOutputAsync(process.StandardError, ProcessOutput, cancellationToken, readCancellation.Token);","sourceCodeStart":383,"sourceCodeEnd":419,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting.Foundry/FoundryLocalService.cs#L383-L419","documentation":"RunProcessAsync starts the `foundry` CLI as a child process and throws this InvalidOperationException when Process.Start() returns false, i.e. the OS refused to launch the executable. Since CreateFoundryStartInfo uses UseShellExecute=false with the literal executable name \"foundry\", this almost always means the foundry executable could not be resolved or executed on PATH.","triggerScenarios":"Any RunFoundryCommandCoreAsync call (model load, model info, service start/stop, daemon-verb probe) where Process.Start() returns false — typically because no `foundry` (or foundry.exe) binary is on the PATH of the app-host process, or the file exists but is not executable.","commonSituations":"Foundry Local CLI never installed on the dev machine; installed via a mechanism that doesn't add it to PATH; the app host runs in an environment (IDE launch profile, CI agent, container) with a different PATH than the user shell; on Linux/macOS the binary lacks the execute bit.","solutions":["Install the Foundry Local CLI and verify `foundry --version` works in the same shell/environment that launches the AppHost.","If installed, add its install directory to the PATH visible to the app host process (check IDE/launchSettings environment, not just your terminal).","On Linux/macOS, ensure the binary has the executable bit: chmod +x $(which foundry).","Restart the IDE/terminal after installation so it picks up the updated PATH."],"exampleFix":"// before: launch profile without foundry on PATH fails to start the CLI\n// after: extend the app host's PATH so `foundry` resolves (launchSettings.json):\n// \"environmentVariables\": { \"PATH\": \"/usr/local/bin:%PATH%\" }\n// verify first:\n// $ foundry --version","handlingStrategy":"validation","validationCode":"// Pre-flight check the user can run before launching the AppHost:\npublic static bool IsFoundryCliAvailable()\n{\n    try\n    {\n        using var p = Process.Start(new ProcessStartInfo(\"foundry\", \"--version\") { RedirectStandardOutput = true, UseShellExecute = false });\n        return p is not null;\n    }\n    catch (System.ComponentModel.Win32Exception)\n    {\n        return false;\n    }\n}","typeGuard":null,"tryCatchPattern":"try\n{\n    await foundry.StartAsync();\n}\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"could not be started\"))\n{\n    throw new InvalidOperationException(\n        \"The 'foundry' CLI was not found on PATH. Install Foundry Local and restart your terminal/IDE.\", ex);\n}","preventionTips":["Verify `foundry --version` resolves in the same environment that launches the AppHost (IDE, CI agent, container).","Document the Foundry Local CLI as a prerequisite and fail fast with a clear check in dev scripts.","After installing or updating the CLI, restart terminals and IDEs so PATH changes are picked up.","On Linux/macOS, confirm the binary is executable after install."],"tags":["foundry","cli","process-start","path"],"backgroundTag":"command-not-found","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}