microsoft/aspire · error · AzureProvisioningFailureException

AzureProvisioningFailureException (request failure details…

Error message

AzureProvisioningFailureException (request failure details, location availability)

What it means

When the deployment exception has no per-operation FailureDetails, BicepProvisioner builds AzureProvisioningFailureDetails from the RequestFailedException itself. If the details indicate a location availability failure (capacity/sku unavailable in the chosen region), the details are enriched (EnrichFailureDetailsAsync) with region suggestions and then thrown as AzureProvisioningFailureException. This distinguishes region-capacity problems from generic template errors.

Solutions

Switch the resource's region: override the location for the resource (or the whole AppHost) to a region with capacity.
Review the enriched failure details / logs for the suggested alternate regions and pick one.
Request quota or regional access for the SKU if the region is required.
Retry later if it is a transient capacity shortage (capacity errors are often time-limited).

Example fix

// before
var cosmos = builder.AddAzureCosmosDB("cosmos"); // defaults to AppHost location without capacity

// after
var cosmos = builder.AddAzureCosmosDB("cosmos").WithAnnotation(new AzureLocationAnnotation("westus2"));

Defensive patterns

Strategy: try-catch

Validate before calling

// Check the SKU is offered in the target region before deploying
az vm list-skus --location <region> --size <sku-family> --output table

Type guard

static bool IsLocationAvailability(AzureProvisioningFailureException ex) => ex.FailureDetails?.IsLocationAvailabilityFailure == true;

Try / catch

try
{
    await provisioner.GetOrCreateResourceAsync(resource, ct);
}
catch (AzureProvisioningFailureException ex) when (ex.FailureDetails?.IsLocationAvailabilityFailure == true)
{
    // pick an alternate region from ex.FailureDetails (enriched with suggestions) and retry once
}

Prevention

Pin known-capacity regions for SKUs your app requires.
Handle the enriched failure details to surface alternate-region suggestions in tooling.
Verify subscription regional access/quota before first deploy to a new region.

When it happens

Trigger: ARM request fails with an error whose failure details (FromRequestFailedException) have IsLocationAvailabilityFailure set - e.g. SKU/capacity errors like 'SkuNotAvailable' or zonal capacity errors - during GetOrCreateResourceAsync deployment for the resource's effective location.

Common situations: Provisioning resources in a region without capacity (e.g. Premium SKU in a smaller region), restricted subscription not enabled for a region/zonal SKU, or a location that doesn't support the requested SKU family.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Azure/Provisioning/Provisioners/BicepProvisioner.cs:739

                context,
                deploymentId,
                effectiveLocation,
                deploymentOperationTracker,
                force: true,
                statePersistenceCancellationToken).ConfigureAwait(false);

            if (summary.FailedOperations.FirstOrDefault(static operation => operation.FailureDetails is not null)?.FailureDetails is { } failureDetails)
            {
                LogProvisioningFailure(resourceLogger, failureDetails);
                throw new AzureProvisioningFailureException(failureDetails, ex);
            }

            var requestFailureDetails = AzureProvisioningFailureDetails.FromRequestFailedException(ex, AzureProvisioningFailureDetails.ProvisionOperation);
            if (requestFailureDetails.IsLocationAvailabilityFailure)
            {
                requestFailureDetails = await EnrichFailureDetailsAsync(requestFailureDetails, context, effectiveLocation, cancellationToken).ConfigureAwait(false);
                LogProvisioningFailure(resourceLogger, requestFailureDetails);
                throw new AzureProvisioningFailureException(requestFailureDetails, ex);
            }

            LogProvisioningFailure(resourceLogger, requestFailureDetails);
            throw;
        }
        catch (OperationCanceledException)
        {
            if (await TryCancelDeploymentAsync(deployments, deploymentName, resourceLogger, treatMissingOrInactiveAsCanceled: true).ConfigureAwait(false) &&
                stateSection is not null)
            {
                UpdateDeploymentState(stateSection, locationOverride, deploymentId, parameters, outputObj: null, scope, checksum, effectiveLocation, DeploymentStateProvisioningStateCanceled);
                await deploymentStateManager.SaveSectionAsync(stateSection, statePersistenceCancellationToken).ConfigureAwait(false);
            }

            throw;
        }
        finally
        {

View on GitHub (pinned to 25830f84bd)