microsoft/aspire · critical · DistributedApplicationException

Container runtime ' ' could not be found. See…

Error message

Container runtime '{containerRuntime}' could not be found. See https://aka.ms/aspire/containers for more details on supported container runtimes.

What it means

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.

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.

Example fix

// before: podman not initialized, docker not installed
// after: initialize podman machine (shell, not C#)
// podman machine init && podman machine start

Defensive patterns

Strategy: validation

Validate before calling

var exe = OperatingSystem.IsWindows() ? "docker.exe" : "docker";
var runtimeOnPath = Environment.GetEnvironmentVariable("PATH")
    ?.Split(Path.PathSeparator)
    .Any(dir => File.Exists(Path.Combine(dir, exe)) || File.Exists(Path.Combine(dir, "podman")));
if (runtimeOnPath != true) throw new InvalidOperationException("No container runtime (docker/podman) found on PATH.");

Try / catch

try
{
    await distributedApplication.RunAsync();
}
catch (DistributedApplicationException ex) when (ex.Message.Contains("could not be found"))
{
    Console.Error.WriteLine($"{ex.Message} Install Docker Desktop or Podman and ensure it is on PATH.");
}

Prevention

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.

When it happens

Trigger: During DCP dependency checking, the runtime health check reports the container runtime binary not found AND throwIfUnhealthy=true is passed to CheckDcpInfoAndLogErrors.

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

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting/Dcp/DcpDependencyCheck.cs:243

    {
        var containerRuntime = options.ContainerRuntime;
        if (string.IsNullOrEmpty(containerRuntime))
        {
            // Default runtime is Docker
            containerRuntime = KnownContainerRuntimes.Docker;
        }
        var installed = dcpInfo.Containers?.Installed ?? false;
        var running = dcpInfo.Containers?.Running ?? false;
        var error = dcpInfo.Containers?.Error;

        if (!installed)
        {
            logger.LogWarning("Container runtime '{Runtime}' could not be found. See https://aka.ms/aspire/containers for more details on supported container runtimes.", containerRuntime);

            logger.LogDebug("The error from the container runtime check was: {Error}", error);
            if (throwIfUnhealthy)
            {
                throw new DistributedApplicationException($"Container runtime '{containerRuntime}' could not be found. See https://aka.ms/aspire/containers for more details on supported container runtimes.");
            }
        }
        else if (!running)
        {
            var (message, linkUrl) = BuildContainerRuntimeUnhealthyMessage(containerRuntime);

            // For logging, we want the template format with {Runtime} placeholder
            var logMessage = message.Replace($"'{containerRuntime}'", "'{Runtime}'");
            if (linkUrl is not null)
            {
                logMessage += " For more information, visit: " + linkUrl;
            }

            logger.LogWarning(logMessage, containerRuntime);

            logger.LogDebug("The error from the container runtime check was: {Error}", error);
            if (throwIfUnhealthy)
            {

View on GitHub (pinned to 25830f84bd)