microsoft/aspire · error · MissingConfigurationException

Azure resources cannot be managed because the Azure…

Error message

Azure resources cannot be managed because the Azure subscription ID is missing or invalid.

What it means

Thrown when creating the ARM client because the resolved Azure subscription ID is missing or not a valid GUID. The controller resolves the subscription from configuration or the current Azure context, validates it with Guid.TryParse, and refuses to manage resources without a well-formed subscription ID.

Solutions

Set the Azure subscription ID configuration (e.g. AZURE_SUBSCRIPTION_ID env var or appsettings) to a valid GUID.
Run 'az login' and 'az account set --subscription <guid>' so the current Azure context has a valid subscription.
Verify with 'az account show --query id' that the resolved subscription is a GUID and copy it exactly.
Clear and re-create the cached Azure context if it holds a stale subscription value.

Example fix

// before
set AZURE_SUBSCRIPTION_ID=My Subscription
// after
set AZURE_SUBSCRIPTION_ID=00000000-0000-0000-0000-000000000000

Defensive patterns

Strategy: validation

Validate before calling

// validate subscription before building the ARM client
var sub = Environment.GetEnvironmentVariable("AZURE_SUBSCRIPTION_ID")
          ?? azureConfig.SubscriptionId;
if (string.IsNullOrWhiteSpace(sub) || !Guid.TryParse(sub, out _))
{
    throw new InvalidOperationException(
        "Set AZURE_SUBSCRIPTION_ID to a valid subscription GUID before running.");
}

Type guard

bool HasValidSubscriptionId(string? sub) => Guid.TryParse(sub, out _);

Try / catch

try { var client = armClientProvider.GetArmClient(credential, subscriptionId); }
catch (MissingConfigurationException ex) when (ex.Message.Contains("subscription ID is missing or invalid"))
{
    // prompt for/repair subscription config, then retry
}

Prevention

Always set AZURE_SUBSCRIPTION_ID to the GUID, never the subscription display name.
Run 'az login' and 'az account set --subscription <guid>' before provisioning.
Validate the ID with Guid.TryParse in startup checks.
Copy the subscription ID from 'az account show --query id -o tsv'.

When it happens

Trigger: Calling PrepareResources/ARM client creation when the subscriptionId variable is null/empty/not a GUID — e.g. no subscription configured and GetCurrentAzureContextAsync returned a context with a missing or malformed SubscriptionId.

Common situations: AZURE_SUBSCRIPTION_ID env var unset or contains a display name instead of a GUID; not logged in with az login so no context; stale/corrupted local Azure context; typo in config value.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Azure/AzureProvisioningController.cs:3083

    private async Task<IArmClient> GetArmClientForResourceIdAsync(string resourceId, CancellationToken cancellationToken)
    {
        string? subscriptionId = null;
        if (ResourceIdentifier.TryParse(resourceId, out var parsedResourceId) &&
            parsedResourceId is not null)
        {
            // Prefer the subscription embedded in the ARM resource ID. This makes cleanup resilient
            // after the user changes Azure context but still has cached state for old resources.
            subscriptionId = parsedResourceId.SubscriptionId;
        }

        if (string.IsNullOrWhiteSpace(subscriptionId))
        {
            subscriptionId = (await GetCurrentAzureContextAsync(cancellationToken).ConfigureAwait(false)).SubscriptionId;
        }

        if (!Guid.TryParse(subscriptionId, out _))
        {
            throw new MissingConfigurationException("Azure resources cannot be managed because the Azure subscription ID is missing or invalid.");
        }

        var armClientProvider = serviceProvider.GetRequiredService<IArmClientProvider>();
        var tokenCredentialProvider = serviceProvider.GetRequiredService<ITokenCredentialProvider>();
        return armClientProvider.GetArmClient(tokenCredentialProvider.TokenCredential, subscriptionId);
    }

    private static string? TryGetCachedDeploymentId(DeploymentStateSection section)
        => section.Data["Id"]?.GetValue<string>() is { Length: > 0 } deploymentId ? deploymentId : null;

    private static bool IsActiveCachedDeployment(DeploymentStateSection section)
        => string.Equals(
            section.Data[BicepProvisioner.DeploymentStateProvisioningStateKey]?.GetValue<string>(),
            BicepProvisioner.DeploymentStateProvisioningStateRunning,
            StringComparison.Ordinal);

    private static bool IsArmDeploymentResourceId(string resourceId)
    {

View on GitHub (pinned to 25830f84bd)