microsoft/aspire · error · DistributedApplicationException

Container runtime ' ' was found but appears to be unhealthy.

Error message

Container runtime '{containerRuntime}' was found but appears to be unhealthy. {additionalDetails}

What it means

Same health-check path as the not-found case, but here the container runtime binary exists yet responds as unhealthy; the message includes additional details. With throwIfUnhealthy it throws DistributedApplicationException, otherwise it only logs a warning.

Solutions

Start the container runtime/daemon (open Docker Desktop, 'podman machine start', 'systemctl start docker').
Wait for the daemon to finish starting and re-run the AppHost.
Check daemon status ('docker info' / 'podman info') and fix the reported problem (permissions, WSL, socket).
Reinstall or update the runtime if the daemon repeatedly fails to start.

Example fix

// start the daemon before running the AppHost (shell)
// sudo systemctl start docker   (Linux)
// open -a Docker                (macOS)
// podman machine start          (podman)

Defensive patterns

Strategy: retry

Validate before calling

// confirm the daemon is actually answering before starting the AppHost
var probe = await ExecAsync("docker info"); // or 'podman info'
if (probe.ExitCode != 0) throw new InvalidOperationException("Container daemon is not responding; start it first.");

Try / catch

try
{
    await distributedApplication.RunAsync();
}
catch (DistributedApplicationException ex) when (ex.Message.Contains("unhealthy"))
{
    logger.LogWarning("Runtime unhealthy: {Details}. Will prompt user to start daemon.", ex.Message);
}

Prevention

Start Docker Desktop/podman machine before launching AppHosts, especially after reboots.
Add a health-wait loop (docker info until success) to dev environment setup scripts.
Check WSL2 backend status on Windows when the daemon won't start.
Watch for daemon socket permission errors after Docker upgrades.

When it happens

Trigger: CheckDcpInfoAndLogErrors receives a runtime check result indicating the runtime is installed but not running/healthy (e.g. 'docker ps' or equivalent failed), and throwIfUnhealthy=true.

Common situations: Docker Desktop installed but daemon not started, podman machine stopped, daemon restarting after reboot, WSL backend not started, or daemon socket permission problems.

Related errors

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

Appendix: source

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

            }
        }
        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)
            {
                throw new DistributedApplicationException(message);
            }
        }
    }
}

View on GitHub (pinned to 25830f84bd)