microsoft/aspire · error · InvalidOperationException

Could not find DCP executable in the Aspire layout.

Error message

Could not find DCP executable in the Aspire layout.

What it means

After confirming layout services exist, ResolveDetachedUnixLauncherAsync asks DcpExecutableResolver to locate the 'dcp-fork-process' executable shipped with the Aspire layout. When it cannot be found, the CLI refuses to proceed with a detached Unix launch and throws this InvalidOperationException, because forking a detached child without the DCP helper is unsupported.

Solutions

  1. Reinstall or repair the Aspire CLI so the complete layout including the DCP bundle is present.
  2. Let the bundle service re-download the DCP bundle, then retry the launch.
  3. Verify the resolved layout directory actually contains the 'dcp-fork-process' executable.
  4. Use attached (non-detached) execution as a fallback when no layout is available.
Defensive patterns

Strategy: fallback

Validate before calling

var dcp = await DcpExecutableResolver.TryGetDcpExecutableAsync(layout, bundles, ctx, "dcp-fork-process", ct);
if (dcp is null) { /* repair layout or fall back */ }

Try / catch

try { await executor.StartAsync(spec, detached: true); }
catch (InvalidOperationException ex) when (ex.Message.Contains("DCP executable"))
{
    logger.LogWarning("DCP missing from layout; reinstalling or falling back.");
    await executor.StartAsync(spec, detached: false);
}

Prevention

When it happens

Trigger: StartAsync with detached Unix launch where TryGetDcpExecutableAsync returns null: the DCP bundle is missing or not yet downloaded, the Aspire layout is incomplete/corrupted, or the CLI was run from a non-standard installation without the DCP artifact.

Common situations: Partial or interrupted CLI installation; running the CLI from a source build without the DCP bundle; a version mismatch where the installed layout predates dcp-fork-process; cleaning the bundle cache and launching before re-acquisition.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Cli/DotNet/ProcessExecution.cs:171

        if (!_options.Detached || OperatingSystem.IsWindows() || _startInfo.DetachedUnixLauncherPath is not null)
        {
            return null;
        }

        if (_layoutDiscovery is null || _bundleService is null || _executionContext is null)
        {
            throw new InvalidOperationException("Detached Unix process launch requires Aspire layout services.");
        }

        var dcpExecutable = await DcpExecutableResolver.TryGetDcpExecutableAsync(
            _layoutDiscovery,
            _bundleService,
            _executionContext,
            "dcp-fork-process",
            cancellationToken).ConfigureAwait(false);
        if (dcpExecutable is null)
        {
            throw new InvalidOperationException("Could not find DCP executable in the Aspire layout.");
        }

        try
        {
            if (dcpExecutable.LayoutLease is not null)
            {
                var environment = _startInfo.Environment
                    .Where(static kvp => kvp.Value is not null)
                    .ToDictionary(static kvp => kvp.Key, static kvp => kvp.Value!, ProcessEnvironment.Comparer);
                dcpExecutable.LayoutLease.AddEnvironment(environment);

                foreach (var (key, value) in environment)
                {
                    _startInfo.Environment[key] = value;
                }
            }

            _startInfo.DetachedUnixLauncherPath = dcpExecutable.ExecutablePath;

View on GitHub (pinned to 25830f84bd)