microsoft/aspire · error · DistributedApplicationException

Container runtime ' ' was not found on PATH. Install or set…

Error message

Container runtime '{RuntimeExecutable}' was not found on PATH. Install {Name} or set ASPIRE_CONTAINER_RUNTIME to a different runtime (e.g., 'docker' or 'podman').

What it means

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.

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.

Example fix

// before: ASPIRE_CONTAINER_RUNTIME=podman with podman not installed
// after: install podman, or set the env var to an available runtime
export ASPIRE_CONTAINER_RUNTIME=docker

Defensive patterns

Strategy: validation

Validate before calling

var runtime = Environment.GetEnvironmentVariable("ASPIRE_CONTAINER_RUNTIME") ?? "docker";
var probe = System.Diagnostics.Process.Start(new System.Diagnostics.ProcessStartInfo(runtime, "--version") { RedirectStandardOutput = true, RedirectStandardError = true });
if (probe is null || probe.WaitForExit(5000) is false || probe.ExitCode != 0)
{
    throw new InvalidOperationException($"Container runtime '{runtime}' is not available on PATH.");
}

Try / catch

try
{
    await model.ComposeUpAsync();
}
catch (DistributedApplicationException ex) when (ex.Message.Contains("was not found on PATH"))
{
    logger.LogWarning(ex, "Container runtime unavailable; skipping compose operations.");
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting/Publishing/ContainerRuntimeBase.cs:919

    protected async Task EnsureRuntimeAvailableAsync()
    {
        try
        {
            var whichCommand = OperatingSystem.IsWindows() ? "where" : "which";
            var spec = new ProcessSpec(whichCommand)
            {
                Arguments = RuntimeExecutable,
                ThrowOnNonZeroReturnCode = false,
                InheritEnv = true
            };

            var (pendingResult, processDisposable) = _processRunner.Run(spec);
            await using (processDisposable)
            {
                var result = await pendingResult.ConfigureAwait(false);
                if (result.ExitCode != 0)
                {
                    throw new DistributedApplicationException(
                        $"Container runtime '{RuntimeExecutable}' was not found on PATH. " +
                        $"Install {Name} or set ASPIRE_CONTAINER_RUNTIME to a different runtime (e.g., 'docker' or 'podman').");
                }
            }
        }
        catch (DistributedApplicationException)
        {
            throw;
        }
        catch (Exception ex)
        {
            _logger.LogDebug(ex, "Failed to check if {Runtime} is available on PATH", RuntimeExecutable);
        }
    }
}

/// <summary>
/// Internal DTO for deserializing Docker Compose ps JSON output.

View on GitHub (pinned to 25830f84bd)