microsoft/aspire · error · InvalidOperationException

Failed to start Developer Control Plane (DCP).

Error message

Failed to start Developer Control Plane (DCP).

What it means

Aspire's environment checker (`aspire doctor` diagnostics) attempts to start a local DCP (Developer Control Plane) server process to verify connectivity. If the process object reports StartAsync returned false - the OS failed to launch the DcpServer executable - the checker throws InvalidOperationException with a generic 'Failed to start DCP' message so the doctor flow can surface and log the failure.

Solutions

  1. Reinstall or update the Aspire CLI/DCP components (`aspire update` or reinstall) so the DCP server binaries exist and match your platform.
  2. Verify the DCP executable path exists and is executable (check antivirus quarantine and file permissions).
  3. Check the doctor output/log for the underlying OS error (missing file, access denied) and fix that root cause.
  4. Confirm you are on a supported OS/architecture for DCP.

Example fix

// user-side: verify DCP binaries exist before diagnosing
var dcpPath = Path.Combine(aspireCliDir, "dcp");
if (!File.Exists(dcpPath))
{
    Console.WriteLine("DCP binaries missing; run 'aspire update' to reinstall.");
    return;
}
Defensive patterns

Strategy: try-catch

Validate before calling

var dcpPath = FindDcpExecutable();
bool launchable = dcpPath is not null && File.Exists(dcpPath) && (OperatingSystem.IsWindows() || HasUnixExecBit(dcpPath));

Try / catch

try { await dcpChecker.CheckAsync(options); }
catch (InvalidOperationException ex) when (ex.Message.Contains("Failed to start Developer Control Plane")) { Console.Error.WriteLine("DCP could not launch - reinstall via 'aspire update' and check AV/permissions."); }

Prevention

When it happens

Trigger: DcpConnectionChecker.StartAsync invoking process.StartAsync (via Hex1b-style process launch) and it returning false - DCP binaries missing/not installed, executable path not found, or OS-level launch failure (bad permissions, incompatible binary).

Common situations: A broken or partial `aspire` install where the DCP binaries were never downloaded, an antivirus quarantining the dcp executable, running on an unsupported platform, or file permission problems in the working directory where DCP is launched.

Related errors

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

Appendix: source

Thrown at src/Aspire.Cli/Utils/EnvironmentChecker/DcpConnectionChecker.cs:275

                // Keeping it under the doctor-owned temp directory prevents overlap with AppHost sessions.
                environmentVariables["DCP_SESSION_FOLDER"] = sessionDirectory;

                var options = new ProcessInvocationOptions
                {
                    StandardOutputCallback = output.AppendOutput,
                    StandardErrorCallback = output.AppendError
                };

                process = processExecutionFactory.CreateExecution(
                    dcpExecutablePath,
                    arguments.ToArray(),
                    environmentVariables,
                    executionContext.WorkingDirectory,
                    options);

                if (!await process.StartAsync(cancellationToken).ConfigureAwait(false))
                {
                    throw new InvalidOperationException(DoctorCommandStrings.DcpStartFailedMessage);
                }

                processStarted = true;
                var session = new DcpConnectionTestSession(process, sessionDirectory, kubeconfigPath, output, logger);
                await session.WaitForKubeconfigFileAsync(cancellationToken).ConfigureAwait(false);
                return session;
            }
            catch
            {
                if (process is not null)
                {
                    try
                    {
                        if (processStarted && !process.HasExited)
                        {
                            process.Kill(entireProcessTree: true);
                        }
                    }

View on GitHub (pinned to 25830f84bd)