microsoft/aspire · error · InvalidOperationException

The certificate bundle cache file prefix contains invalid…

Error message

The certificate bundle cache file prefix contains invalid characters.

What it means

The certificate bundle cache file prefix must contain only ASCII letters, digits, '-' or '_' because it is used to build cache file names. Passing a prefix that is empty, whitespace, or contains other characters throws InvalidOperationException.

Solutions

1. Sanitize the prefix to ASCII letters, digits, '-', or '_' before passing it (e.g. replace invalid chars with '-')
2. Use a short alphanumeric identifier such as the app or component name
3. Check whether the value was assembled from a path or version and strip separators

Example fix

// before
var prefix = packageName + "/" + version; // contains '/'
// after
var prefix = string.Concat(packageName, "-", version.Replace('.', '_'))
    .Where(char.IsAsciiLetterOrDigit or '-' or '_');

var safePrefix = new string(prefix.Where(c => char.IsAsciiLetterOrDigit(c) || c is '-' or '_').ToArray());
if (string.IsNullOrWhiteSpace(safePrefix)) throw new ArgumentException("cacheFilePrefix required");

bool IsValidCachePrefix(string? p) => !string.IsNullOrWhiteSpace(p) && p.All(c => char.IsAsciiLetterOrDigit(c) || c is '-' or '_');

try { var project = new GuestAppHostProject(..., cacheFilePrefix, ...); }
catch (InvalidOperationException ex) when (ex.Message.Contains("cache file prefix"))
{
    prefix = SanitizePrefix(prefix);
}

When it happens

Trigger: Constructing GuestAppHostProject with a cacheFilePrefix containing characters outside [A-Za-z0-9_-] (e.g. spaces, slashes, dots) or an empty/null prefix.

Common situations: Deriving the prefix from a package name, path segment, or version string that contains dots or slashes (e.g. 'My.App/1.0').

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.
• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• ASPIRERADIUS049
• AzureSandboxOptions.AutoDeleteEnabled must be set when…
• AzureSandboxOptions.AutoSuspendEnabled must be set when…
• Cannot derive a Helm release name from resource name
• cert-manager resource name

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

Appendix: source

Thrown at src/Aspire.Cli/Projects/GuestAppHostProject.cs:2258

        string? devCertPemPath,
        string environmentVariableName,
        string cacheFilePrefix,
        CancellationToken cancellationToken)
    {
        if (devCertPemPath is null)
        {
            return;
        }

        if (string.IsNullOrWhiteSpace(environmentVariableName))
        {
            throw new InvalidOperationException("The certificate bundle environment variable name cannot be empty.");
        }

        if (string.IsNullOrWhiteSpace(cacheFilePrefix) ||
            cacheFilePrefix.Any(character => !char.IsAsciiLetterOrDigit(character) && character is not '-' and not '_'))
        {
            throw new InvalidOperationException("The certificate bundle cache file prefix contains invalid characters.");
        }

        // Explicit AppHost configuration takes precedence over the inherited environment.
        // Environment variable names are case-insensitive on Windows.
        var configuredKeys = _environment.IsWindows()
            ? environmentVariables.Keys
                .Where(key => string.Equals(key, environmentVariableName, StringComparison.OrdinalIgnoreCase))
                .ToArray()
            : environmentVariables.ContainsKey(environmentVariableName)
                ? [environmentVariableName]
                : [];
        var existingCertificateBundle = configuredKeys.LastOrDefault() is { } configuredKey
            ? environmentVariables[configuredKey]
            : _environment.GetEnvironmentVariable(environmentVariableName);
        var certificateBundlePath = devCertPemPath;

        if (!string.IsNullOrWhiteSpace(existingCertificateBundle))
        {

View on GitHub (pinned to 25830f84bd)