microsoft/aspire · error · InvalidOperationException

ASPIRERADIUS083

ASPIRERADIUS083

Error message

Environment variable '${envVarName}' on resource '${resource.Name}' holds a credential, so it is published as a Kubernetes secret key, but its name is not a valid one (a key must be 1-253 characters of letters, digits, '-', '_' and '.', and may not be '.' or '..' or start with '..'). Rename the variable. Diagnostic: ASPIRERADIUS083.

What it means

Environment variables that hold credentials on a container are emitted as a Kubernetes Secret, so the variable name becomes the secret data key. Kubernetes requires keys to be 1-253 chars of letters, digits, '-', '_' or '.', not be '.' or '..', and not start with '..'. An invalid name throws ASPIRERADIUS083 via KubernetesName.IsValidSecretDataKey.

Solutions

Rename the environment variable to a valid Kubernetes key: letters, digits, '-', '_', '.', up to 253 chars, not '.' or '..' and not starting with '..'.
Sanitize dynamically generated names before passing them to WithEnvironment.
Move the credential out of the env var name path (e.g., map the config key to a conventional name like ConnectionStrings__MyDb).

Example fix

// before
builder.AddContainer("api", "image")
    .WithEnvironment("my app/connection:secret", secretRef);
// after
builder.AddContainer("api", "image")
    .WithEnvironment("my_app_connection_secret", secretRef);

Defensive patterns

Strategy: validation

Validate before calling

static bool IsValidSecretKey(string name) =>
    name.Length is >= 1 and <= 253 &&
    name.All(c => char.IsLetterOrDigit(c) || c is '-' or '_' or '.') &&
    name is not ("." or "..") && !name.StartsWith("..");

Try / catch

catch (InvalidOperationException ex) when (ex.Message.Contains("ASPIRERADIUS083"))
{
    logger.LogError(ex, "Invalid Kubernetes secret key from env var name");
}

Prevention

Validate env var names against Kubernetes key rules before WithEnvironment.
Sanitize dynamic names (replace illegal chars with '-') instead of passing config keys verbatim.
Prefer conventional names like ConnectionStrings__X for credentials.

When it happens

Trigger: Publishing a container whose credential-bearing environment variable (added with e.g. WithEnvironment(name, value) where the value is treated as a secret) has a name violating Kubernetes secret-key rules (empty, too long, illegal characters, or '../..'-style names).

Common situations: Env var names built dynamically with spaces, slashes, or special characters; very long generated names over 253 chars; names like ".env" siblings or those starting with '..'; names from config keys copied verbatim (e.g., containing ':' or '/').

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Radius/Publishing/RadiusInfrastructureBuilder.cs:3821

    /// <summary>
    /// Maps an environment-variable name to a key of the container's secret.
    /// </summary>
    /// <remarks>
    /// Kubernetes restricts <c>Secret</c> data keys to <c>[-._a-zA-Z0-9]+</c>, caps them at 253
    /// characters, and rejects <c>.</c>, <c>..</c> and any name starting with <c>..</c> — all
    /// narrower than what an environment-variable name may contain. Aspire's own names
    /// (<c>services__*</c>, <c>ConnectionStrings__*</c>, <c>OTEL_*</c>) all satisfy it, but a name
    /// supplied through <c>WithEnvironment</c> need not, and an invalid key is rejected by the API
    /// server at deploy time rather than at publish time. Reject it here instead, where the name can
    /// be attributed. <see cref="KubernetesName.IsValidSecretDataKey"/> carries the full contract,
    /// so it is reused rather than restated as a looser character-class check here.
    /// </remarks>
    private static string ToSecretKey(IResource resource, string envVarName)
    {
        if (!KubernetesName.IsValidSecretDataKey(envVarName))
        {
            throw new InvalidOperationException(
                $"Environment variable '{envVarName}' on resource '{resource.Name}' holds a credential, so it is " +
                $"published as a Kubernetes secret key, but its name is not a valid one (a key must be 1-253 " +
                $"characters of letters, digits, '-', '_' and '.', and may not be '.' or '..' or start with '..'). " +
                $"Rename the variable. Diagnostic: ASPIRERADIUS083.");
        }

        return envVarName;
    }

    /// <summary>
    /// Creates the single <c>Radius.Security/secrets</c> resource holding every credential-bearing
    /// environment value of one container.
    /// </summary>
    /// <remarks>
    /// One secret per container rather than one per variable keeps the emitted artifact
    /// proportional to the number of workloads instead of the number of variables.
    /// <para>
    /// This secret is only ever consumed by its own container, so it cannot create the

View on GitHub (pinned to 25830f84bd)