microsoft/aspire · error · ArgumentException

Cannot set both UseDeveloperCertificate and Certificate…

Error message

Cannot set both UseDeveloperCertificate and Certificate properties.

What it means

HttpsCertificateAnnotation.Certificate's init accessor rejects a certificate when UseDeveloperCertificate was already set to true. The two options configure the same HTTPS certificate slot and are mutually exclusive, so the annotation throws ArgumentException naming the 'value' parameter.

Solutions

Set only one of the two properties: remove UseDeveloperCertificate = true if supplying a real certificate.
Remove the explicit Certificate when the developer certificate is intended.
Read the current annotation state and branch so exactly one property is assigned.
Wrap annotation creation in try/catch (ArgumentException) to surface the config conflict to the user during startup validation.

Example fix

// before
var annotation = new HttpsCertificateAnnotation
{
    UseDeveloperCertificate = true,
    Certificate = new X509Certificate2("cert.pfx", password)
};
// after
var annotation = new HttpsCertificateAnnotation
{
    Certificate = new X509Certificate2("cert.pfx", password)
};

Defensive patterns

Strategy: validation

Validate before calling

// before constructing the annotation
if (useDevCert && explicitCertificate is not null)
    throw new ArgumentException("Specify either UseDeveloperCertificate or Certificate, not both.");

Try / catch

try
{
    var annotation = new HttpsCertificateAnnotation { /* one of the two only */ };
}
catch (ArgumentException ex) when (ex.Message.Contains("UseDeveloperCertificate"))
{
    // report conflicting HTTPS certificate configuration
}

Prevention

Pick one certificate source (dev cert vs explicit) per environment profile.
Never merge HTTPS settings from two config sources onto the same annotation.
Centralize annotation creation in one factory that enforces the exclusivity.
Review object initializers for both properties appearing together.

When it happens

Trigger: Object-initializer or constructor call that sets UseDeveloperCertificate = true and also assigns Certificate = X509Certificate2 (in either order, since the Certificate setter also runs when UseDeveloperCertificate is initialized afterwards).

Common situations: Copy-pasting Kestrel-style certificate config into an Aspire annotation; merging two config sources that each specify a certificate; toggling from developer cert to a real cert but leaving both properties set.

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/cacd9af4728bcb0d. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting/ApplicationModel/HttpsCertificateAnnotation.cs:30

/// </summary>
[Experimental("ASPIRECERTIFICATES001", UrlFormat = "https://aka.ms/aspire/diagnostics/{0}")]
public sealed class HttpsCertificateAnnotation : IResourceAnnotation
{
    private X509Certificate2? _certificate;
    private bool? _useDeveloperCertificate;

    /// <summary>
    /// Sets an <see cref="X509Certificate2"/> instance associated with this annotation.
    /// If a certificate is provided, it must have a private key; otherwise, an <see cref="ArgumentException"/> is thrown when setting the value.
    /// </summary>
    public X509Certificate2? Certificate
    {
        get => _certificate;
        init
        {
            if (value != null && _useDeveloperCertificate == true)
            {
                throw new ArgumentException("Cannot set both UseDeveloperCertificate and Certificate properties.", nameof(value));
            }

            if (value?.HasPrivateKey == false)
            {
                throw new ArgumentException("The provided certificate must have a private key.", nameof(value));
            }

            try
            {
                if (value != null && value.PublicKey == null)
                {
                    throw new ArgumentException("The provided certificate must have a valid public key.", nameof(value));
                }
            }
            catch (CryptographicException ex)
            {
                throw new ArgumentException("The provided certificate is invalid.", nameof(value), ex);
            }

View on GitHub (pinned to 25830f84bd)