{"record":{"id":"1f7c33cc63dd9796","repo":"microsoft/aspire","slug":"message-ensure-runtimeexecutable-is-installed-and-available","errorCode":null,"errorMessage":"{message} Ensure '{RuntimeExecutable}' is installed and available on PATH. {envHint}","messagePattern":"(.+?) Ensure '(.+?)' is installed and available on PATH\\. (.+?)","errorType":"exception","errorClass":"DistributedApplicationException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting/Publishing/ContainerRuntimeBase.cs","lineNumber":695,"sourceCode":"                .ConfigureAwait(false);\n\n            if (processResult.ExitCode != 0)\n            {\n                var envHint = Environment.GetEnvironmentVariable(\"ASPIRE_CONTAINER_RUNTIME\") is not null\n                    ? $\"The container runtime is configured via ASPIRE_CONTAINER_RUNTIME (current: '{RuntimeExecutable}').\"\n                    : $\"The container runtime was auto-detected as '{RuntimeExecutable}'. Set ASPIRE_CONTAINER_RUNTIME to override (e.g., 'docker' or 'podman').\";\n\n                var message =\n                    $\"'{RuntimeExecutable} compose up' failed with exit code {processResult.ExitCode}. \" +\n                    $\"Ensure '{RuntimeExecutable}' is installed and available on PATH. \" +\n                    envHint;\n\n                if (processResult.TotalProcessOutputLineCount > 0)\n                {\n                    message = $\"{message}{Environment.NewLine}{processResult.GetFormattedOutput()}\";\n                }\n\n                throw new DistributedApplicationException(message);\n            }\n        }\n    }\n\n    public virtual async Task ComposeDownAsync(ComposeOperationContext context, CancellationToken cancellationToken)\n    {\n        await EnsureRuntimeAvailableAsync().ConfigureAwait(false);\n\n        var arguments = BuildComposeArguments(context);\n        arguments += \" down\";\n\n        _logger.LogDebug(\"Running {Runtime} compose down with arguments: {Arguments}\", RuntimeExecutable, arguments);\n\n        var stderrLines = new List<string>();\n        var spec = new ProcessSpec(RuntimeExecutable)\n        {\n            Arguments = arguments,\n            WorkingDirectory = context.WorkingDirectory,","sourceCodeStart":677,"sourceCodeEnd":713,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting/Publishing/ContainerRuntimeBase.cs#L677-L713","documentation":"ComposeUpAsync throws DistributedApplicationException when 'docker compose up' fails. The message hints that the runtime executable must be installed and on PATH, plus any environment-specific hint, with process output appended.","triggerScenarios":"Calling ComposeUpAsync during publish when the compose process exits non-zero, or the Compose v2 plugin is missing/unreachable.","commonSituations":"Docker CLI installed but the compose plugin absent (docker-compose v1 only); PATH not containing the runtime in CI containers; compose file errors; port conflicts or daemon not running.","solutions":["Install the compose plugin (docker-compose-plugin) or Docker Desktop with Compose v2 and verify with 'docker compose version'.","Ensure the runtime executable is on PATH for the process running the AppHost.","Read the appended output to fix compose file errors (invalid YAML, missing build context).","Verify the container daemon is running and free ports aren't conflicting."],"exampleFix":"// before: bare docker CLI in CI image\napt-get install -y docker.io\n// after\napt-get install -y docker.io docker-compose-plugin\ndocker compose version","handlingStrategy":"validation","validationCode":"var probe = System.Diagnostics.Process.Start(new System.Diagnostics.ProcessStartInfo(RuntimeExecutable, \"compose version\") { RedirectStandardOutput = true });\nvar composeAvailable = probe is not null && probe.WaitForExit(10000) && probe.ExitCode == 0;\nif (!composeAvailable) throw new InvalidOperationException($\"{RuntimeExecutable} compose plugin is not installed or not on PATH\");","typeGuard":null,"tryCatchPattern":"try { await runtime.ComposeUpAsync(ctx, ct); }\ncatch (DistributedApplicationException ex) when (ex.Message.Contains(\"installed and available on PATH\"))\n{\n    logger.LogError(ex, \"Compose unavailable or failed; check plugin install and PATH\");\n    throw;\n}","preventionTips":["Install docker-compose-plugin (Compose v2) in all environments running publish.","Add the runtime executable to PATH for the AppHost process, including CI containers.","Validate compose files with 'docker compose config' before automating.","Keep the container daemon running and check port availability."],"tags":["docker-compose","publish","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"}