microsoft/aspire · error · InvalidOperationException

Container runtime ' ' is not running or is unhealthy.

Error message

Container runtime '{containerRuntime.Name}' is not running or is unhealthy.

What it means

Aspire's ResourceContainerImageManager builds container images for resources during publish. Before building, it verifies the configured container runtime (Docker/Podman) is reachable via CheckIfRunningAsync. If the runtime is not running or unhealthy it throws InvalidOperationException because image builds cannot proceed without a container engine.

Solutions

Start your container runtime (launch Docker Desktop, or 'podman machine start' for Podman).
Verify the daemon responds: 'docker info' or 'podman info'.
If using a custom runtime, check its configuration and DOCKER_HOST environment variable.
Re-run the publish/build command once the runtime reports healthy.

Example fix

// before (daemon stopped)
aspire publish
// error: Container runtime 'docker' is not running or is unhealthy.

// after
sudo systemctl start docker   # or: open Docker Desktop / podman machine start
aspire publish

Defensive patterns

Strategy: try-catch

Validate before calling

var healthy = await dockerClient.CheckIfRunningAsync(ct);
if (!healthy) throw new InvalidOperationException("Start Docker/Podman before publishing.");

Try / catch

try { await manager.BuildImagesAsync(...); }
catch (InvalidOperationException ex) when (ex.Message.Contains("not running or is unhealthy"))
{
    logger.LogWarning(ex, "Container runtime unavailable; start Docker/Podman and retry.");
}

Prevention

Start Docker Desktop / podman machine before running aspire publish.
Add a preflight 'docker info' check in CI before image builds.
Watch for Docker Desktop auto-update/pause states after reboots.
Verify DOCKER_HOST points at a live daemon.

When it happens

Trigger: Calling BuildImagesAsync (e.g. during 'aspire publish' or publisher pipelines) when no Docker/Podman daemon is running, the daemon socket is unreachable, the container runtime binary is missing, or the daemon is in a paused/unresponsive state.

Common situations: Docker Desktop not started after reboot; Podman machine not initialized; running publish inside CI without a container engine; DOCKER_HOST pointing at a dead remote daemon; Docker daemon crashed mid-session.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting/Publishing/ResourceContainerImageManager.cs:225

        return options;
    }

    public async Task BuildImagesAsync(IEnumerable<IResource> resources, CancellationToken cancellationToken = default)
    {
        var containerRuntime = await GetContainerRuntimeAsync(cancellationToken).ConfigureAwait(false);
        logger.LogInformation("Starting to build container images");

        // Only check container runtime health if there are resources that need it
        if (await ResourcesRequireContainerRuntimeAsync(resources, cancellationToken).ConfigureAwait(false))
        {
            logger.LogDebug("Checking {ContainerRuntimeName} health", containerRuntime.Name);

            var containerRuntimeHealthy = await containerRuntime.CheckIfRunningAsync(cancellationToken).ConfigureAwait(false);

            if (!containerRuntimeHealthy)
            {
                logger.LogError("Container runtime '{ContainerRuntimeName}' is not running or is unhealthy. Cannot build container images.", containerRuntime.Name);
                throw new InvalidOperationException($"Container runtime '{containerRuntime.Name}' is not running or is unhealthy.");
            }

            logger.LogDebug("{ContainerRuntimeName} is healthy", containerRuntime.Name);
        }

        foreach (var resource in resources)
        {
            // TODO: Consider parallelizing this.
            await BuildImageAsync(resource, cancellationToken).ConfigureAwait(false);
        }

        logger.LogDebug("Building container images completed");
    }

    public async Task BuildImageAsync(IResource resource, CancellationToken cancellationToken = default)
    {
        var containerRuntime = await GetContainerRuntimeAsync(cancellationToken).ConfigureAwait(false);
        logger.LogInformation("Building container image for resource {ResourceName}", resource.Name);

View on GitHub (pinned to 25830f84bd)