microsoft/aspire · error · DistributedApplicationException

Ensure ' ' is installed and available on PATH.

Error message

{message} Ensure '{RuntimeExecutable}' is installed and available on PATH. {envHint}

What it means

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.

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.

Example fix

// before: bare docker CLI in CI image
apt-get install -y docker.io
// after
apt-get install -y docker.io docker-compose-plugin
docker compose version

Defensive patterns

Strategy: validation

Validate before calling

var probe = System.Diagnostics.Process.Start(new System.Diagnostics.ProcessStartInfo(RuntimeExecutable, "compose version") { RedirectStandardOutput = true });
var composeAvailable = probe is not null && probe.WaitForExit(10000) && probe.ExitCode == 0;
if (!composeAvailable) throw new InvalidOperationException($"{RuntimeExecutable} compose plugin is not installed or not on PATH");

Try / catch

try { await runtime.ComposeUpAsync(ctx, ct); }
catch (DistributedApplicationException ex) when (ex.Message.Contains("installed and available on PATH"))
{
    logger.LogError(ex, "Compose unavailable or failed; check plugin install and PATH");
    throw;
}

Prevention

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.

When it happens

Trigger: Calling ComposeUpAsync during publish when the compose process exits non-zero, or the Compose v2 plugin is missing/unreachable.

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

Related errors

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

Appendix: source

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

                .ConfigureAwait(false);

            if (processResult.ExitCode != 0)
            {
                var envHint = Environment.GetEnvironmentVariable("ASPIRE_CONTAINER_RUNTIME") is not null
                    ? $"The container runtime is configured via ASPIRE_CONTAINER_RUNTIME (current: '{RuntimeExecutable}')."
                    : $"The container runtime was auto-detected as '{RuntimeExecutable}'. Set ASPIRE_CONTAINER_RUNTIME to override (e.g., 'docker' or 'podman').";

                var message =
                    $"'{RuntimeExecutable} compose up' failed with exit code {processResult.ExitCode}. " +
                    $"Ensure '{RuntimeExecutable}' is installed and available on PATH. " +
                    envHint;

                if (processResult.TotalProcessOutputLineCount > 0)
                {
                    message = $"{message}{Environment.NewLine}{processResult.GetFormattedOutput()}";
                }

                throw new DistributedApplicationException(message);
            }
        }
    }

    public virtual async Task ComposeDownAsync(ComposeOperationContext context, CancellationToken cancellationToken)
    {
        await EnsureRuntimeAvailableAsync().ConfigureAwait(false);

        var arguments = BuildComposeArguments(context);
        arguments += " down";

        _logger.LogDebug("Running {Runtime} compose down with arguments: {Arguments}", RuntimeExecutable, arguments);

        var stderrLines = new List<string>();
        var spec = new ProcessSpec(RuntimeExecutable)
        {
            Arguments = arguments,
            WorkingDirectory = context.WorkingDirectory,

View on GitHub (pinned to 25830f84bd)