microsoft/aspire · error · DcpDeveloperCertificateUnavailableException

No fully trusted exportable developer certificate with a…

Error message

No fully trusted exportable developer certificate with a private key was found.

What it means

To secure the DCP connection, the checker looks for the ASP.NET Core developer HTTPS certificate that is fully trusted and exportable with a private key. AddDeveloperCertificateArguments throws DcpDeveloperCertificateUnavailableException when no matching certificate exists, because DCP requires a trusted, exportable dev cert to configure TLS.

Solutions

Run `dotnet dev-certs https --trust` to create and trust a fresh developer certificate, then rerun the doctor check.
If a certificate exists but is untrusted, re-trust it (`dotnet dev-certs https --clean` then `--trust`).
On Linux, ensure the dev cert was exported/installed into the system CA store (dotnet dev-certs handles this on supported distros).
Verify with `dotnet dev-certs https --check --trust` that a fully trusted cert with a private key exists before running doctor.

Example fix

// shell fix
// before: doctor fails: no fully trusted exportable dev cert
dotnet dev-certs https --clean
dotnet dev-certs https --trust
// then rerun: aspire doctor

Defensive patterns

Strategy: validation

Validate before calling

// shell precheck before running doctor
dotnet dev-certs https --check --trust
// exit code 0 + 'Trusted' means a trusted dev cert exists

Try / catch

try { await checker.CheckAsync(options); }
catch (DcpDeveloperCertificateUnavailableException ex) { Console.Error.WriteLine($"Run 'dotnet dev-certs https --trust' first. ({ex.Message})"); }

Prevention

Run `dotnet dev-certs https --trust` on new machines, containers, and after cert expiration.
Periodically check with `dotnet dev-certs https --check --trust`.
On Linux/macOS confirm trust steps completed for the current user session.

When it happens

Trigger: DcpConnectionChecker.StartAsync calls AddDeveloperCertificateArguments and the X509 certificate enumeration finds no certificate that simultaneously HasPrivateKey and has CertificateManager trust level Full - e.g. `dotnet dev-certs https` never run, cert untrusted in the OS store, or non-exportable key.

Common situations: Fresh machines or CI containers where the dev certificate was never created/trusted, expired dev certificates that were removed, macOS keychain certs without exportable private keys, Linux machines where the cert wasn't trusted into the system store.

Understand the failure class

SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

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

Appendix: source

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

                .TakeLast(40)
                .Select(line => $"{line.Stream}: {line.Line}")
                .ToArray();

            return lines.Length == 0 ? DoctorCommandStrings.DcpNoOutputDetails : string.Join(Environment.NewLine, lines);
        }

        private static void AddDeveloperCertificateArguments(List<string> arguments, CertificateManager certificateManager, IEnvironment environment)
        {
            var certificates = certificateManager.ListCertificates(StoreName.My, StoreLocation.CurrentUser, isValid: true);
            try
            {
                var certificate = certificates.FirstOrDefault(c =>
                    c.HasPrivateKey &&
                    certificateManager.GetTrustLevel(c) == CertificateManager.TrustLevel.Full);

                if (certificate is null)
                {
                    throw new DcpDeveloperCertificateUnavailableException(DoctorCommandStrings.DcpDeveloperCertificateNoTrustedExportableDetails);
                }

                if (string.IsNullOrWhiteSpace(certificate.Thumbprint))
                {
                    throw new DcpDeveloperCertificateUnavailableException(DoctorCommandStrings.DcpDeveloperCertificateMissingThumbprintDetails);
                }

                arguments.Add("--tls-cert-thumbprint");
                arguments.Add(certificate.Thumbprint);

                if (environment.IsWindows())
                {
                    return;
                }

                var certificatePath = DcpDeveloperCertificateCache.EnsureDeveloperCertificateCache(certificateManager, certificate);
                var keyPath = Path.ChangeExtension(certificatePath, ".key");

View on GitHub (pinned to 25830f84bd)