{"record":{"id":"408d1638add2cf4c","repo":"microsoft/aspire","slug":"failed-to-start-dcp-fork-process","errorCode":null,"errorMessage":"Failed to start DCP fork-process.","messagePattern":"Failed to start DCP fork-process\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Cli/Processes/IsolatedProcess.Unix.cs","lineNumber":48,"sourceCode":"\n        dcpStartInfo.ArgumentList.Add(\"fork-process\");\n        dcpStartInfo.ArgumentList.Add(\"--monitor\");\n        dcpStartInfo.ArgumentList.Add(Environment.ProcessId.ToString(CultureInfo.InvariantCulture));\n        dcpStartInfo.ArgumentList.Add(\"--monitor-identity-time\");\n        dcpStartInfo.ArgumentList.Add(ProcessTreeGracefulShutdownService.FormatDcpProcessStartTime(GetCurrentProcessDcpMonitorStartTime()));\n        dcpStartInfo.ArgumentList.Add(\"--\");\n        dcpStartInfo.ArgumentList.Add(startInfo.FileName);\n        foreach (var arg in startInfo.ArgumentList)\n        {\n            dcpStartInfo.ArgumentList.Add(arg);\n        }\n\n        ProcessEnvironment.ApplyTo(dcpStartInfo, startInfo.GetEnvironmentForSpawn());\n\n        cancellationToken.ThrowIfCancellationRequested();\n\n        var dcpProcess = Process.Start(dcpStartInfo)\n            ?? throw new InvalidOperationException(\"Failed to start DCP fork-process.\");\n\n        var stderrTask = dcpProcess.StandardError.ReadToEndAsync(CancellationToken.None);\n        var stdoutLineTask = dcpProcess.StandardOutput.ReadLineAsync(CancellationToken.None).AsTask();\n\n        try\n        {\n            // Once DCP has started, wait for it to report the detached child PID even if the caller\n            // cancels. Without the PID, callers cannot clean up a child that was already forked.\n            var stdoutLine = await stdoutLineTask.ConfigureAwait(false);\n            if (stdoutLine is null)\n            {\n                await dcpProcess.WaitForExitAsync(CancellationToken.None).ConfigureAwait(false);\n                var stderr = await stderrTask.ConfigureAwait(false);\n                throw new InvalidOperationException($\"DCP fork-process did not return a child process ID. DCP fork-process exited with code {dcpProcess.ExitCode}. stderr: '{stderr.Trim()}'\");\n            }\n\n            var trimmedStdout = stdoutLine.Trim();\n            // DCP fork-process writes only the detached child PID followed by a newline, for example:","sourceCodeStart":30,"sourceCodeEnd":66,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Cli/Processes/IsolatedProcess.Unix.cs#L30-L66","documentation":"After building the DCP ProcessStartInfo, StartDetachedUnixAsync calls Process.Start and throws if the OS returns null, meaning the DCP fork-process could not be launched at all. This indicates a pre-exec failure (bad path, missing binary, exec permissions) rather than a runtime error from DCP itself.","triggerScenarios":"Process.Start(dcpStartInfo) returns null during StartAsync's detached Unix launch: DetachedUnixLauncherPath points to a nonexistent, non-executable, or incompatible (wrong arch/OS) binary.","commonSituations":"A truncated or partially extracted DCP binary after an interrupted install; wrong-architecture binary (arm64 vs x64); file lacks +x permission; path corrupted after an upgrade.","solutions":["Verify the DCP path exists and is executable (ls -l $path; chmod +x $path).","Reinstall/repair the Aspire CLI to restore a complete DCP binary for your platform/arch.","Run the DCP binary directly in a terminal to see the OS-level error.","Check CPU architecture matches the binary (file $path on Linux/macOS)."],"exampleFix":"// before: launcher binary present but not executable\n// after\nchmod +x /path/to/dcp\nvar dcpProcess = Process.Start(dcpStartInfo)\n    ?? throw new InvalidOperationException(\"Failed to start DCP fork-process.\");","handlingStrategy":"validation","validationCode":"var path = startInfo.DetachedUnixLauncherPath!;\nif (!File.Exists(path)) throw new FileNotFoundException(\"DCP launcher not found\", path);\nif (!(File.GetUnixFileMode(path) & UnixFileMode.Execute).HasFlag(UnixFileMode.Execute))\n    throw new UnauthorizedAccessException($\"DCP launcher is not executable: {path}\");","typeGuard":null,"tryCatchPattern":"try\n{\n    await process.StartAsync(ct);\n}\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"Failed to start DCP fork-process\"))\n{\n    // check launcher exists, is executable, and matches the machine architecture\n}","preventionTips":["Verify the DCP binary exists and is +x after each install/upgrade","Confirm the binary matches OS and CPU architecture","Reinstall the CLI if the DCP binary looks truncated"],"tags":["process","dcp","unix","process-start"],"backgroundTag":"command-not-found","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}