{"record":{"id":"17502741fd17517f","repo":"microsoft/aspire","slug":"container-runtime-containerruntime-could-not-be-found-see","errorCode":null,"errorMessage":"Container runtime '{containerRuntime}' could not be found. See https://aka.ms/aspire/containers for more details on supported container runtimes.","messagePattern":"Container runtime '(.+?)' could not be found\\. See https://aka\\.ms/aspire/containers for more details on supported container runtimes\\.","errorType":"exception","errorClass":"DistributedApplicationException","httpStatus":null,"severity":"critical","filePath":"src/Aspire.Hosting/Dcp/DcpDependencyCheck.cs","lineNumber":243,"sourceCode":"    {\n        var containerRuntime = options.ContainerRuntime;\n        if (string.IsNullOrEmpty(containerRuntime))\n        {\n            // Default runtime is Docker\n            containerRuntime = KnownContainerRuntimes.Docker;\n        }\n        var installed = dcpInfo.Containers?.Installed ?? false;\n        var running = dcpInfo.Containers?.Running ?? false;\n        var error = dcpInfo.Containers?.Error;\n\n        if (!installed)\n        {\n            logger.LogWarning(\"Container runtime '{Runtime}' could not be found. See https://aka.ms/aspire/containers for more details on supported container runtimes.\", containerRuntime);\n\n            logger.LogDebug(\"The error from the container runtime check was: {Error}\", error);\n            if (throwIfUnhealthy)\n            {\n                throw new DistributedApplicationException($\"Container runtime '{containerRuntime}' could not be found. See https://aka.ms/aspire/containers for more details on supported container runtimes.\");\n            }\n        }\n        else if (!running)\n        {\n            var (message, linkUrl) = BuildContainerRuntimeUnhealthyMessage(containerRuntime);\n\n            // For logging, we want the template format with {Runtime} placeholder\n            var logMessage = message.Replace($\"'{containerRuntime}'\", \"'{Runtime}'\");\n            if (linkUrl is not null)\n            {\n                logMessage += \" For more information, visit: \" + linkUrl;\n            }\n\n            logger.LogWarning(logMessage, containerRuntime);\n\n            logger.LogDebug(\"The error from the container runtime check was: {Error}\", error);\n            if (throwIfUnhealthy)\n            {","sourceCodeStart":225,"sourceCodeEnd":261,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting/Dcp/DcpDependencyCheck.cs#L225-L261","documentation":"CheckDcpInfoAndLogErrors verifies the configured container runtime (docker/podman). When the runtime executable cannot be found it logs a warning and, if throwIfUnhealthy is set, throws a DistributedApplicationException with a link to aka.ms/aspire/containers. Containers cannot run without a usable runtime.","triggerScenarios":"During DCP dependency checking, the runtime health check reports the container runtime binary not found AND throwIfUnhealthy=true is passed to CheckDcpInfoAndLogErrors.","commonSituations":"Docker Desktop not installed or not on PATH, podman machine never initialized, running in CI/container images without a container runtime, or PATH differences between shell and AppHost process.","solutions":["Install or repair the configured runtime (Docker Desktop, Podman) and ensure it is on PATH.","Start the runtime (launch Docker Desktop, or 'podman machine init && podman machine start').","Verify with 'docker --version' / 'podman --version' in the same environment the AppHost runs in.","Point Aspire at the correct runtime via the container runtime configuration option if multiple runtimes exist.","See https://aka.ms/aspire/containers for supported runtimes."],"exampleFix":"// before: podman not initialized, docker not installed\n// after: initialize podman machine (shell, not C#)\n// podman machine init && podman machine start","handlingStrategy":"validation","validationCode":"var exe = OperatingSystem.IsWindows() ? \"docker.exe\" : \"docker\";\nvar runtimeOnPath = Environment.GetEnvironmentVariable(\"PATH\")\n    ?.Split(Path.PathSeparator)\n    .Any(dir => File.Exists(Path.Combine(dir, exe)) || File.Exists(Path.Combine(dir, \"podman\")));\nif (runtimeOnPath != true) throw new InvalidOperationException(\"No container runtime (docker/podman) found on PATH.\");","typeGuard":null,"tryCatchPattern":"try\n{\n    await distributedApplication.RunAsync();\n}\ncatch (DistributedApplicationException ex) when (ex.Message.Contains(\"could not be found\"))\n{\n    Console.Error.WriteLine($\"{ex.Message} Install Docker Desktop or Podman and ensure it is on PATH.\");\n}","preventionTips":["Install a supported runtime before running Aspire (see aka.ms/aspire/containers).","For Podman, always create and start the podman machine first.","In CI images, explicitly install the runtime and add it to PATH.","Verify with 'docker --version' in the same shell/environment that launches the AppHost."],"tags":["container-runtime","docker","podman","prerequisite"],"backgroundTag":"container-runtime-missing","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"}