{"record":{"id":"357a758a5f22ce20","repo":"microsoft/aspire","slug":"azureprovisioningfailureexception-deployment-failure-details","errorCode":null,"errorMessage":"AzureProvisioningFailureException (deployment failure details)","messagePattern":"AzureProvisioningFailureException \\(deployment failure details\\)","errorType":"exception","errorClass":"AzureProvisioningFailureException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Hosting.Azure/Provisioning/Provisioners/BicepProvisioner.cs","lineNumber":665,"sourceCode":"            var failureDetails = AzureProvisioningFailureDetails.FromRequestFailedException(ex, AzureProvisioningFailureDetails.ProvisionOperation);\n            if (!failureDetails.IsLocationAvailabilityFailure)\n            {\n                LogProvisioningFailure(resourceLogger, failureDetails);\n                throw;\n            }\n\n            failureDetails = await EnrichFailureDetailsAsync(failureDetails, context, effectiveLocation, cancellationToken).ConfigureAwait(false);\n            if (context.ExecutionContext.IsRunMode)\n            {\n                await notificationService.PublishUpdateAsync(resource, state => state with\n                {\n                    State = new(AzureProvisioningStrings.ResourceStateAzureDeploymentFailed, KnownResourceStateStyles.Error),\n                    Properties = failureDetails.SetResourceProperties(WithoutDeploymentOperationProperties(state.Properties), AzureProvisioningFailureDetails.ProvisionOperation)\n                }).ConfigureAwait(false);\n            }\n\n            LogProvisioningFailure(resourceLogger, failureDetails);\n            throw new AzureProvisioningFailureException(failureDetails, ex);\n        }\n\n        // Run mode keeps persisting deployment state and final diagnostics after cancellation so\n        // Ctrl+C leaves enough information for recovery. Publish/deploy should still honor the\n        // caller's cancellation token because those operations are command-scoped.\n        var statePersistenceCancellationToken = context.ExecutionContext.IsRunMode ? CancellationToken.None : cancellationToken;\n        DeploymentStateSection? stateSection = null;\n        string? locationOverride = null;\n\n        if (context.ExecutionContext.IsRunMode)\n        {\n            var sectionName = $\"Azure:Deployments:{resource.Name}\";\n            stateSection = await deploymentStateManager.AcquireSectionAsync(sectionName, statePersistenceCancellationToken).ConfigureAwait(false);\n            locationOverride = stateSection.Data[AzureProvisioningController.LocationOverrideKey]?.GetValue<string>();\n            UpdateDeploymentState(stateSection, locationOverride, deploymentId, parameters, outputObj: null, scope, checksum, effectiveLocation, DeploymentStateProvisioningStateRunning);\n            await deploymentStateManager.SaveSectionAsync(stateSection, statePersistenceCancellationToken).ConfigureAwait(false);\n        }\n        // Resolve the deployment URL before waiting for the operation to complete","sourceCodeStart":647,"sourceCodeEnd":683,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Hosting.Azure/Provisioning/Provisioners/BicepProvisioner.cs#L647-L683","documentation":"During GetOrCreateResourceAsync, when the ARM deployment creation fails, Aspire collects deployment-operation failure details (from ARM's deployment operations), logs them, updates the resource state to 'Azure deployment failed' with the enriched failure details, and throws AzureProvisioningFailureException wrapping the original exception and details. This gives the developer a single exception carrying per-operation ARM error codes/messages instead of a bare RequestFailedException.","triggerScenarios":"A Bicep deployment submitted by GetOrCreateResourceAsync fails: ARM returns a provisioning failure (template validation error, resource-level error, quota, naming conflict, RP not registered, auth/permission failure on a nested resource). The exception is thrown after LogProvisioningFailure with AzureProvisioningFailureDetails populated from deployment operations.","commonSituations":"Invalid Bicep template or parameters; region capacity/quota limits; resource name already taken or invalid characters; missing role assignments/permissions for managed identities; unregistered resource providers; wrong subscription or location values in provisioning options.","solutions":["Read AzureProvisioningFailureException.FailureDetails (and the logged output) for the exact ARM error code and target resource; fix that specific error.","Check the deployment error details in the Azure portal (Resource Group > Deployments > failed deployment) if the exception details are insufficient.","Fix common causes: correct parameter values, register missing resource providers, resolve quota/naming conflicts, grant required RBAC roles.","Re-run the app host after fixing; the deployment is retried on the next provisioning run.","Catch AzureProvisioningFailureException in automation to access structured failure details programmatically instead of parsing logs."],"exampleFix":"// before\ntry\n{\n    await GetOrCreateResourceAsync(resource, context);\n}\ncatch (Exception ex)\n{\n    logger.LogError(ex, \"provisioning failed\");   // loses ARM per-operation detail\n}\n\n// after\ntry\n{\n    await GetOrCreateResourceAsync(resource, context);\n}\ncatch (AzureProvisioningFailureException ex)\n{\n    foreach (var detail in ex.FailureDetails.Operations)\n    {\n        logger.LogError(\"{Target}: {Code} - {Message}\", detail.Target, detail.Code, detail.Message);\n    }\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"if (ex is AzureProvisioningFailureException apfe)\n{\n    foreach (var op in apfe.FailureDetails.Operations)\n    {\n        Console.WriteLine($\"{op.Target}: {op.Status} {op.Code}: {op.Message}\");\n    }\n}","tryCatchPattern":"try\n{\n    await provisioner.GetOrCreateResourceAsync(resource, context, ct);\n}\ncatch (AzureProvisioningFailureException ex)\n{\n    logger.LogError(ex, \"Deployment failed. ARM operations: {Details}\", ex.FailureDetails);\n}","preventionTips":["Run az deployment group what-if (or deploy the Bicep standalone) to catch template and permission errors before provisioning through Aspire.","Pre-check quota, region capacity, and resource-provider registration for all resource types your Bicep references.","Ensure the signed-in identity has Contributor (or equivalent) on the target resource group/subscription.","Catch AzureProvisioningFailureException specifically (not bare Exception) so structured ARM failure details are available to your error handling.","Keep AppHost Bicep parameters in sync with required resource properties to avoid parameter-validation failures."],"tags":["azure","bicep","deployment","arm","provisioning-failure"],"backgroundTag":"deployment-failed","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}