microsoft/aspire · error · MissingConfigurationException

An Azure subscription id is required. Set the…

Error message

An Azure subscription id is required. Set the Azure:SubscriptionId configuration value.

What it means

BaseProvisioningContextProvider.CreateProvisioningContextAsync requires an Azure subscription id to create a ProvisioningContext. When options.SubscriptionId is null it throws MissingConfigurationException directing you to set the Azure:SubscriptionId configuration value. Aspire provisioning cannot target Azure without knowing which subscription to deploy into.

Solutions

Add "Azure": { "SubscriptionId": "<your-sub-id>" } to appsettings.json or user secrets of the AppHost.
Set the environment variable Azure__SubscriptionId (or AZURE_SUBSCRIPTION_ID if wired that way) before running the AppHost.
Run `azd auth login` / `az login` and initialize the environment (azd init or provision once) so the value is captured.
Or set options.SubscriptionId programmatically when configuring the Azure provisioning options.

Example fix

// appsettings.json
// before
{ }
// after
{ "Azure": { "SubscriptionId": "00000000-0000-0000-0000-000000000000" } }

Defensive patterns

Strategy: validation

Validate before calling

var subId = configuration["Azure:SubscriptionId"];
if (string.IsNullOrEmpty(subId))
{
    throw new InvalidOperationException("Set Azure:SubscriptionId (appsettings or Azure__SubscriptionId env var) before provisioning.");
}

Try / catch

try { await provider.CreateProvisioningContextAsync(ct); } catch (MissingConfigurationException ex) when (ex.Message.Contains("SubscriptionId")) { /* prompt user to configure subscription */ }

Prevention

Run `azd init` or `azd provision` once so Azure settings (subscription, location) are persisted.
Keep Azure:SubscriptionId in user secrets for local dev.
Set Azure__SubscriptionId in CI environment variables.

When it happens

Trigger: Running an AppHost that provisions Azure resources with no SubscriptionId in options and no Azure:SubscriptionId configuration entry (appsettings.json, environment variable Azure__SubscriptionId, or AZURE_SUBSCRIPTION_ID depending on setup).

Common situations: Fresh checkout without azd/az login setup; running in CI without the config value; local user secrets never initialized; switching machines where the Azure state/config was not carried over.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Azure/Provisioning/Internal/BaseProvisioningContextProvider.cs:93

        // Must start with a letter
        if (!char.IsLetter(name[0]))
        {
            return false;
        }

        // Cannot end with a period
        if (name.EndsWith('.'))
        {
            return false;
        }

        // No consecutive periods
        return !name.Contains("..");
    }

    public virtual async Task<ProvisioningContext> CreateProvisioningContextAsync(CancellationToken cancellationToken = default)
    {
        var subscriptionId = _options.SubscriptionId ?? throw new MissingConfigurationException("An Azure subscription id is required. Set the Azure:SubscriptionId configuration value.");

        var credential = _tokenCredentialProvider.TokenCredential;

        if (_tokenCredentialProvider is DefaultTokenCredentialProvider defaultProvider)
        {
            defaultProvider.LogCredentialType();
        }

        var armClient = _armClientProvider.GetArmClient(credential, subscriptionId);

        var (subscriptionResource, tenantResource) = await armClient.GetSubscriptionAndTenantAsync(cancellationToken).ConfigureAwait(false);

        _logger.LogInformation("Default subscription: {name} ({subscriptionId})", subscriptionResource.DisplayName, subscriptionResource.Id);
        _logger.LogInformation("Tenant: {tenantId}", tenantResource.TenantId);

        if (string.IsNullOrEmpty(_options.Location))
        {
            throw new MissingConfigurationException("An azure location/region is required. Set the Azure:Location configuration value.");

View on GitHub (pinned to 25830f84bd)