{"record":{"id":"3fdfd75c4e8eec4a","repo":"microsoft/aspire","slug":"container-runtime-runtimeexecutable-was-not-found-on-path","errorCode":null,"errorMessage":"Container runtime '{RuntimeExecutable}' was not found on PATH. Install {Name} or set ASPIRE_CONTAINER_RUNTIME to a different runtime (e.g., 'docker' or 'podman').","messagePattern":"Container runtime '(.+?)' was not found on PATH\\. Install (.+?) or set ASPIRE_CONTAINER_RUNTIME to a different runtime \\(e\\.g\\., 'docker' or 'podman'\\)\\.","errorType":"exception","errorClass":"DistributedApplicationException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting/Publishing/ContainerRuntimeBase.cs","lineNumber":919,"sourceCode":"    protected async Task EnsureRuntimeAvailableAsync()\n    {\n        try\n        {\n            var whichCommand = OperatingSystem.IsWindows() ? \"where\" : \"which\";\n            var spec = new ProcessSpec(whichCommand)\n            {\n                Arguments = RuntimeExecutable,\n                ThrowOnNonZeroReturnCode = false,\n                InheritEnv = true\n            };\n\n            var (pendingResult, processDisposable) = _processRunner.Run(spec);\n            await using (processDisposable)\n            {\n                var result = await pendingResult.ConfigureAwait(false);\n                if (result.ExitCode != 0)\n                {\n                    throw new DistributedApplicationException(\n                        $\"Container runtime '{RuntimeExecutable}' was not found on PATH. \" +\n                        $\"Install {Name} or set ASPIRE_CONTAINER_RUNTIME to a different runtime (e.g., 'docker' or 'podman').\");\n                }\n            }\n        }\n        catch (DistributedApplicationException)\n        {\n            throw;\n        }\n        catch (Exception ex)\n        {\n            _logger.LogDebug(ex, \"Failed to check if {Runtime} is available on PATH\", RuntimeExecutable);\n        }\n    }\n}\n\n/// <summary>\n/// Internal DTO for deserializing Docker Compose ps JSON output.","sourceCodeStart":901,"sourceCodeEnd":937,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting/Publishing/ContainerRuntimeBase.cs#L901-L937","documentation":"Aspire needs a container runtime (Docker, Podman, etc.) to execute compose-style operations. Before running a compose command, EnsureRuntimeAvailableAsync probes the runtime executable; if the probe process exits non-zero (typically because the executable does not exist on PATH), it throws this DistributedApplicationException naming the configured runtime and suggesting alternatives. It wraps the low-level process failure into a clear, actionable message.","triggerScenarios":"Calling ComposeUpAsync, ComposeDownAsync, or ComposeListServicesAsync when the configured container runtime executable (RuntimeExecutable, default resolved from ASPIRE_CONTAINER_RUNTIME or known runtimes) is not present or not runnable on PATH, so the probe command (e.g. 'docker version') exits with a non-zero code.","commonSituations":"Docker/Podman is not installed; the runtime daemon CLI is not on PATH (e.g. Docker Desktop not started, WSL without docker CLI, CI agent without Docker); ASPIRE_CONTAINER_RUNTIME points to a runtime that is not installed; running inside a container/sandbox without a container runtime.","solutions":["Install the container runtime named in the message (Docker Desktop, podman, etc.) and ensure its CLI is on PATH.","Start the runtime (e.g. launch Docker Desktop) if it is installed but the daemon/CLI is unavailable.","Set ASPIRE_CONTAINER_RUNTIME to a runtime that is installed, e.g. 'docker' or 'podman'.","Verify with '<runtime> --version' in the same shell/environment the app host runs in."],"exampleFix":"// before: ASPIRE_CONTAINER_RUNTIME=podman with podman not installed\n// after: install podman, or set the env var to an available runtime\nexport ASPIRE_CONTAINER_RUNTIME=docker","handlingStrategy":"validation","validationCode":"var runtime = Environment.GetEnvironmentVariable(\"ASPIRE_CONTAINER_RUNTIME\") ?? \"docker\";\nvar probe = System.Diagnostics.Process.Start(new System.Diagnostics.ProcessStartInfo(runtime, \"--version\") { RedirectStandardOutput = true, RedirectStandardError = true });\nif (probe is null || probe.WaitForExit(5000) is false || probe.ExitCode != 0)\n{\n    throw new InvalidOperationException($\"Container runtime '{runtime}' is not available on PATH.\");\n}","typeGuard":null,"tryCatchPattern":"try\n{\n    await model.ComposeUpAsync();\n}\ncatch (DistributedApplicationException ex) when (ex.Message.Contains(\"was not found on PATH\"))\n{\n    logger.LogWarning(ex, \"Container runtime unavailable; skipping compose operations.\");\n}","preventionTips":["Pre-flight check '<runtime> --version' in setup scripts and CI before starting the app host.","Start Docker Desktop / podman machine before running Aspire apps.","Document and pin ASPIRE_CONTAINER_RUNTIME per environment."],"tags":["containers","docker","podman","environment","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"}