microsoft/aspire · critical · FileNotFoundException

The Developer Control Plane is not installed at

Error message

The Developer Control Plane is not installed at "{dcpExePath}". The application cannot be run without it.

What it means

DcpHost.CreateDcpProcessSpec verifies that the DCP CLI executable exists at the configured path before building the process spec to start the Developer Control Plane API server. If the file is missing it throws FileNotFoundException — the app cannot run because DCP orchestrates containers/executables. The message includes the checked path and the path is passed as the FileNotFoundException's fileName.

Solutions

Clear the DCP cache (delete ~/.aspine/bin or the dcp folder under the user profile) and rerun the AppHost so a matching DCP is downloaded.
Check ASPIRE_DCP_CLI_PATH / ASPIRE_DCP_LOCATION environment variables and remove or correct them if they point at a missing binary.
Verify the file actually exists at the path in the message (ls the path) and reinstall if absent.
Ensure the Aspire.Hosting package restored fully (dotnet restore) so its DCP acquisition step can run.

Example fix

// before: stale env override
export ASPIRE_DCP_CLI_PATH=/opt/old-dcp/dcp
// after: unset overrides and let Aspire resolve DCP
unset ASPIRE_DCP_CLI_PATH
unset ASPIRE_DCP_LOCATION
dotnet run --project AppHost

Defensive patterns

Strategy: validation

Validate before calling

var dcpPath = DcpHost.GetDcpCliPath(); // or your resolved DcpOptions.CliPath
if (string.IsNullOrEmpty(dcpPath) || !File.Exists(dcpPath))
{
    throw new InvalidOperationException($"DCP CLI missing at '{dcpPath}'. Clear the Aspire cache and rerun.");
}

Type guard

static bool IsDcpInstalled(string? cliPath) =>
    !string.IsNullOrWhiteSpace(cliPath) && File.Exists(cliPath);

Try / catch

try { await app.RunAsync(); }
catch (FileNotFoundException ex) when (ex.Message.Contains("Developer Control Plane is not installed"))
{
    // trigger DCP re-download or correct ASPIRE_DCP_CLI_PATH, then retry
}

Prevention

Do not set ASPIRE_DCP_CLI_PATH/ASPIRE_DCP_LOCATION unless necessary
Re-restore packages and clear ~/.aspine/bin after upgrades
Verify DCP presence in CI before running AppHosts
Check antivirus quarantine if the path keeps disappearing

When it happens

Trigger: Launching the AppHost when DcpOptions.CliPath points to a nonexistent dcp binary — DCP never installed, install failed or was partially deleted, ASPIRE_DCP_CLI_PATH/ASPIRE_DCP_LOCATION env vars pointing at wrong locations, or version skew after an Aspire upgrade left stale paths.

Common situations: CI machines without the DCP download step; ~/.aspine/bin cache cleaned or corrupted; manually setting DCP env overrides incorrectly; running the AppHost on a platform/arch where the DCP binary was not restored; antivirus quarantining the binary.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting/Dcp/DcpHost.cs:300

                dcpProcessSpec.EnvironmentVariables.Add("DCP_LOG_FILE_NAME_SUFFIX", _dcpOptions.LogFileNameSuffix);
            }

            _logProcessorTask = Task.Run(() => StartLoggingSocketAsync(loggingSocket));
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Failed to enable orchestration logging.");
        }

        _ = ProcessUtil.Run(dcpProcessSpec);
    }

    public ProcessSpec CreateDcpProcessSpec(Locations locations)
    {
        var dcpExePath = _dcpOptions.CliPath;
        if (!File.Exists(dcpExePath))
        {
            throw new FileNotFoundException($"The Developer Control Plane is not installed at \"{dcpExePath}\". The application cannot be run without it.", dcpExePath);
        }

        var arguments = $"start-apiserver --monitor {Environment.ProcessId} --detach --kubeconfig \"{locations.DcpKubeconfigPath}\"";
        if (!string.IsNullOrEmpty(_dcpOptions.ContainerRuntime))
        {
            arguments += $" --container-runtime \"{_dcpOptions.ContainerRuntime}\"";
        }

        if (!string.IsNullOrWhiteSpace(_dcpTlsCertThumbprint))
        {
            arguments += $" --tls-cert-thumbprint \"{_dcpTlsCertThumbprint}\"";
        }

        if (!string.IsNullOrWhiteSpace(_dcpTlsCertFile) && !string.IsNullOrWhiteSpace(_dcpTlsKeyFile))
        {
            arguments += $" --tls-cert-file \"{_dcpTlsCertFile}\" --tls-key-file \"{_dcpTlsKeyFile}\"";
        }

View on GitHub (pinned to 25830f84bd)