microsoft/aspire · error · MissingParameterValueException

OpenAI API key parameter

Error message

OpenAI API key parameter '{name}-openai-apikey' is missing and OPENAI_API_KEY environment variable is not set.

What it means

AddOpenAI creates a default secret API key parameter by reading configuration key 'Parameters:{name}-openai-apikey' and then the OPENAI_API_KEY environment variable. If both are absent it throws MissingParameterValueException, because the OpenAI client resource requires an API key to inject into dependent projects. This fail-fast ensures the model resource is never created without usable credentials.

Solutions

  1. Export the OPENAI_API_KEY environment variable in the shell or launchSettings.json before running the AppHost.
  2. Add the value to AppHost configuration under Parameters:{name}-openai-apikey (e.g. in user secrets or appsettings.Development.json).
  3. Supply an explicit pre-created secret parameter via WithApiKey instead of relying on the default parameter.

Example fix

// before (fails if key missing)
var openai = builder.AddOpenAI("openai");
// after
dotnet user-secrets set "Parameters:openai-openai-apikey" "sk-..." # or
export OPENAI_API_KEY=sk-...
var openai = builder.AddOpenAI("openai");
Defensive patterns

Strategy: validation

Validate before calling

if (builder.Configuration["Parameters:openai-openai-apikey"] is null &&
    Environment.GetEnvironmentVariable("OPENAI_API_KEY") is null)
{
    throw new InvalidOperationException("Provide an OpenAI API key via user secrets or OPENAI_API_KEY before AddOpenAI.");
}

Prevention

When it happens

Trigger: Calling builder.AddOpenAI("openai") when neither the config key 'Parameters:openai-openai-apikey' (e.g. via appsettings.json or a parameter entry) nor the OPENAI_API_KEY environment variable is set in the AppHost process.

Common situations: Running the AppHost on a new machine or CI where OPENAI_API_KEY is not exported; forgetting a user-secrets entry; key typo in parameter name; deploying without the secrets provisioned.

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

Appendix: source

Thrown at src/Aspire.Hosting.OpenAI/OpenAIExtensions.cs:35

    /// Adds an OpenAI parent resource that can host multiple models.
    /// </summary>
    /// <param name="builder">The <see cref="IDistributedApplicationBuilder"/>.</param>
    /// <param name="name">The name of the OpenAI resource.</param>
    /// <returns>The OpenAI resource builder.</returns>
    [AspireExport]
    public static IResourceBuilder<OpenAIResource> AddOpenAI(this IDistributedApplicationBuilder builder, [ResourceName] string name)
    {
        ArgumentNullException.ThrowIfNull(builder);
        ArgumentException.ThrowIfNullOrEmpty(name);

        var defaultApiKeyParameter = builder.AddParameter($"{name}-openai-apikey", () =>
        {
            var configKey = $"Parameters:{name}-openai-apikey";
            var value = builder.Configuration.GetValueWithNormalizedKey(configKey);
            
            return value ??
                Environment.GetEnvironmentVariable("OPENAI_API_KEY") ??
                throw new MissingParameterValueException($"OpenAI API key parameter '{name}-openai-apikey' is missing and OPENAI_API_KEY environment variable is not set.");
        },
            secret: true);
        defaultApiKeyParameter.Resource.Description = """
            The API key used to authenticate requests to the OpenAI API.
            You can obtain an API key from the [OpenAI API Keys page](https://platform.openai.com/api-keys).
            """;
        defaultApiKeyParameter.Resource.EnableDescriptionMarkdown = true;

        var resource = new OpenAIResource(name, defaultApiKeyParameter.Resource);

        defaultApiKeyParameter.WithParentRelationship(resource);

        // Register the health check
        var healthCheckKey = $"{name}_check";

        // Ensure IHttpClientFactory is available by registering HTTP client services
        builder.Services.AddHttpClient();

View on GitHub (pinned to 25830f84bd)