microsoft/aspire · critical · InvalidOperationException

AppHost:ResourceService:ApiKey is not specified in…

Error message

AppHost:ResourceService:ApiKey is not specified in configuration.

What it means

ResourceServiceOptions holds an optional API key used to authenticate dashboard/resource-service communication, cached as UTF-8 bytes. GetApiKeyBytes is the forceful accessor: if no key was configured it throws rather than returning null, because the caller requires a key to operate. Options validation normally catches this at startup, but this path can still be hit when the value is missing.

Solutions

Set 'AppHost:ResourceService:ApiKey' in configuration (appsettings.json, environment variable AppHost__ResourceService__ApiKey, or user secrets)
Ensure ResourceServiceOptions validation runs at startup so the failure surfaces early with a clear message
Verify the configuration source is actually loaded (correct environment name, config file copied to output)
Only call GetApiKeyBytes when the ApiKey property is confirmed non-null

Example fix

// before
var key = options.GetApiKeyBytes(); // throws when unset
// after
var key = options.ApiKey is null
    ? throw new InvalidOperationException("Configure AppHost:ResourceService:ApiKey before starting the resource service.")
    : options.GetApiKeyBytes();

Defensive patterns

Strategy: validation

Validate before calling

var apiKey = configuration["AppHost:ResourceService:ApiKey"];
if (string.IsNullOrEmpty(apiKey))
{
    throw new InvalidOperationException("Set AppHost:ResourceService:ApiKey before using the resource service.");
}

Type guard

bool HasApiKey(ResourceServiceOptions o) => o.ApiKey is not null;

Try / catch

try
{
    var keyBytes = options.GetApiKeyBytes();
}
catch (InvalidOperationException ex) when (ex.Message.Contains("AppHost:ResourceService:ApiKey"))
{
    // Fail fast with setup guidance pointing at the missing config key.
}

Prevention

Always configure AppHost:ResourceService:ApiKey when the resource service is enabled
Rely on ValidateResourceServiceOptions (IValidateOptions) to catch this at startup
Use environment variable AppHost__ResourceService__ApiKey in containers/CI
Store the key in user secrets locally, never in source control

When it happens

Trigger: Accessing ResourceServiceOptions.GetApiKeyBytes when configuration lacks the 'AppHost:ResourceService:ApiKey' key — e.g. the dashboard resource service is enabled without an API key set in configuration/environment.

Common situations: Running the AppHost/dashboard locally without the expected configuration section; missing ASPNETCORE/environment config source; appsettings for the ResourceService not being loaded; upgrading Aspire where the key became required for the enabled scenario.

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting/Dashboard/ResourceServiceOptions.cs:38

{
    private string? _apiKey;
    private byte[]? _apiKeyBytes;

    public ResourceServiceAuthMode? AuthMode { get; set; }

    public string? ApiKey
    {
        get => _apiKey;
        set
        {
            _apiKey = value;
            _apiKeyBytes = value is null ? null : Encoding.UTF8.GetBytes(value);
        }
    }

    internal byte[] GetApiKeyBytes()
    {
        return _apiKeyBytes ?? throw new InvalidOperationException($"AppHost:ResourceService:ApiKey is not specified in configuration.");
    }
}

internal sealed class ValidateResourceServiceOptions : IValidateOptions<ResourceServiceOptions>
{
    public ValidateOptionsResult Validate(string? name, ResourceServiceOptions options)
    {
        List<string>? errorMessages = null;

        if (options.AuthMode is ResourceServiceAuthMode.ApiKey)
        {
            if (string.IsNullOrWhiteSpace(options.ApiKey))
            {
                AddError($"AppHost:ResourceService:ApiKey is required when AppHost:ResourceService:AuthMode is '{nameof(ResourceServiceAuthMode.ApiKey)}'.");
            }
        }

        return errorMessages is { Count: > 0 }

View on GitHub (pinned to 25830f84bd)