Troubleshoot Azure landing zone for Nonprofits

Use this article to resolve issues that can occur when you deploy or review Azure landing zone for Nonprofits. Start with the exact error message in the Azure portal deployment, Azure CLI installer output, or deployment summary.

If the error isn't listed here, review the failed deployment operation in Azure Resource Manager. For more information, see What is deployment troubleshooting?.

Azure CLI installer can't start

The Azure CLI installer stops before validation or deployment begins.

Common messages:

  • PowerShell 7 or later is required.
  • Azure CLI is required but was not found on PATH.
  • Azure CLI 2.76.0 or later is required.
  • Azure CLI Bicep support is required.
  • Azure authentication is required.

Resolution:

  1. Run the installer from PowerShell 7 or later.
  2. Install or update Azure CLI to version 2.76.0 or later.
  3. Confirm that Azure CLI is available on PATH.
  4. Run az bicep version. If it doesn't work, run az bicep install or az bicep upgrade.
  5. Sign in to the correct tenant with az login --tenant <tenant-id>.
  6. Run the installer again with -Action validate before you run what-if or create.

For more information, see Deploy Azure landing zone for Nonprofits with the Azure CLI.

Azure CLI installer can't access a selected subscription or management group

The Azure CLI installer might stop when it checks the selected deployment scope or parameter values.

Common messages:

  • We could not access the selected subscription '<subscription>'.
  • We could not access the selected management group '<management-group>'.
  • Expanded platform requires parameter 'managementSubscriptionId' in the effective parameter set.
  • Expanded platform requires parameter 'connectivitySubscriptionId' in the effective parameter set.

Resolution:

  1. Confirm that you're signed in to the correct Microsoft Entra tenant.
  2. Confirm that the subscription IDs or names in the config file are correct.
  3. For foundation, confirm that scope.subscription points to the existing foundation subscription.
  4. For expanded platform, confirm that managementSubscriptionId and connectivitySubscriptionId point to existing subscriptions that the deployment identity can access.
  5. If platformManagementGroupId is supplied, confirm that the management group exists and that the deployment identity can access it.
  6. Run validate again before you run what-if or create.

Deployment fails because the identity doesn't have enough permissions

The Azure portal, Azure CLI installer, or Azure Resource Manager can report missing authorization permissions before or during deployment.

Common messages:

  • Authorization permission preflight detected missing permissions for the deployment identity.
  • Authorization preflight failed.
  • AuthorizationFailed
  • You need permission to create Azure Policy assignments in the selected management subscription.
  • You need permission to create Azure RBAC role assignments in the selected connectivity subscription.

Resolution:

  1. Confirm that the Microsoft Entra administrator role isn't used as a substitute for Azure RBAC access.
  2. For foundation, grant Owner on the selected foundation subscription, or equivalent custom access that can create subscription deployments, Azure Policy assignments, and Azure RBAC role assignments.
  3. For expanded platform, grant the deployment identity permission to start tenant-scope deployments and Owner on every selected platform subscription.
  4. If platformManagementGroupId is supplied, grant permission to create Azure Policy set definitions and policy assignments at that existing platform management group.
  5. If temporary elevated access is used for deployment, remove it after deployment is complete.

For more information, see Azure roles, Microsoft Entra roles, and classic subscription administrator roles and Troubleshoot common Azure deployment errors.

Budget creation fails or is blocked by preflight

Budget creation is optional. It runs only when the monthly budget amount is greater than 0 and at least one budget contact email is provided.

Common messages:

  • Budget write permission (Microsoft.Consumption/budgets/write) is NOT currently available.
  • Budget preflight failed: Microsoft.Consumption/budgets/write is not available for the deployment identity at the target budget subscription scope.

Resolution:

  1. If you don't want the deployment to create a budget, set monthlyBudgetAmount to 0 and create the budget manually after deployment.
  2. If you want automatic budget creation, provide a positive monthly budget amount and at least one budget contact email.
  3. Grant Cost Management Contributor, Contributor, or Owner on the subscription where the budget is created.
  4. For foundation, check budget permissions on the foundation subscription.
  5. For expanded platform, check budget permissions on the management subscription.
  6. If the subscription is created recently, wait for Cost Management budget features to become available before retrying budget creation.

For more information, see Create and manage budgets.

Service owner or group object ID values are rejected

The Azure portal or Azure CLI installer validates some input formats before deployment starts.

Common messages:

  • Enter a valid email address or shared alias.
  • ServiceOwner must be a valid email address or shared mailbox alias, for example platform@example.org.
  • Enter a Microsoft Entra group object ID in GUID format (not a user object ID), or leave this blank.

Resolution:

  1. Enter the service owner as an email address or shared mailbox alias, such as platform@example.org.
  2. For organization platform administrators or partner operators, use Microsoft Entra group object IDs, not user object IDs.
  3. Leave optional group fields blank when access is configured after deployment.
  4. Complete customer-owned access before handover. For more information, see Post-deployment tasks for Azure landing zone for Nonprofits.

Foundation private endpoint deployment fails validation

Foundation supports private Key Vault connectivity only when the simple foundation network baseline is also selected.

Symptom: The deployment fails validation after private DNS and Key Vault private endpoint access are requested for foundation without the simple network baseline.

Resolution:

  1. If foundation needs private Key Vault access, enable the simple foundation network baseline and rerun validation.
  2. If foundation doesn't need private Key Vault access, leave private DNS and private endpoint access disabled.
  3. Review the what-if result before you create the deployment.

Key Vault name is already in use or blocked by soft delete

Key Vault names are globally unique. A deleted vault can also block reuse of the same name until the soft-delete retention period expires or an authorized operator purges the vault.

Symptom: Deployment fails when creating the platform Key Vault, even though the target resource group doesn't contain an active vault with that name.

Resolution:

  1. Check whether a soft-deleted Key Vault exists with the generated name.
  2. Recover the deleted vault if it should be kept, or purge it only when deletion is approved and permitted by your organization's retention policy.
  3. For Azure CLI deployments, use a different keyVaultNameSeed parameter override when you need to avoid a soft-deleted generated name.
  4. Rerun validation and what-if before creating the deployment again.

For more information, see Azure Key Vault: soft-delete overview.

Key Vault public endpoint is enabled but data-plane access is denied

The default Key Vault public endpoint is protected by a deny-by-default firewall. The deployment supplies no IP or virtual-network allow rules and doesn't allow a trusted-service bypass.

Symptom: The Key Vault resource is visible in the Azure portal, but secret, key, or certificate operations fail from public networks.

Resolution:

  1. Confirm that the Key Vault firewall uses Deny as its default action and None as its bypass setting. This state is expected.
  2. Enable the supported private endpoint option when administrators or workloads require durable Key Vault data-plane access.
  3. Configure and verify private DNS resolution from the relevant virtual network.
  4. Treat the IP and virtual-network allowlists as deployment-owned and use the private endpoint option for durable data-plane connectivity.

Key Vault private endpoint is enabled but access doesn't work as expected

Private endpoint access changes how administrators and workloads reach the platform Key Vault.

Symptom: The deployment selected private Key Vault connectivity, but clients can't reach the Key Vault through the expected private network path.

Resolution:

  1. Confirm that the deployment result shows that the private endpoint access is selected.
  2. For foundation, confirm that the simple foundation network baseline is also selected.
  3. For expanded platform, confirm that the hub virtual network exists in the connectivity subscription.
  4. Verify private DNS resolution from the virtual network that should reach the Key Vault.
  5. If durable data-plane access is required, keep the private endpoint path. The firewall-restricted public endpoint doesn't provide a persistent allowlist extension point.

Foundation workloads can't reach the internet

The optional Foundation application subnet uses an NSG that denies internet ingress and egress, has defaultOutboundAccess disabled, and doesn't include NAT Gateway or another outbound connectivity method.

Symptom: A workload deployed to the Foundation application subnet can't reach an internet destination.

Resolution:

  1. Confirm that the workload is deployed to the Foundation application subnet.
  2. Review the effective NSG rules and confirm that the baseline internet deny rules are present.
  3. Add only the required higher-priority workload allow rules after security review.
  4. Add an approved explicit outbound connectivity method when the workload requires internet access.

Deployment succeeds but customer-owned access isn't configured

A deployment can succeed even when operational ownership isn't assigned to the organization. This state means the selected platform baseline was created, but handover isn't complete because customer-owned administrator access still needs to be configured and verified.

Symptom: The deployment summary or post-deployment review shows that handover readiness isn't complete, or the organization platform administrators group was left blank during deployment.

Resolution:

  1. Confirm whether customerPlatformAdminsGroupObjectId is supplied during deployment.
  2. If it isn't supplied, assign the appropriate customer-owned Microsoft Entra group after deployment.
  3. Verify Owner access for the customer-owned group on the foundation subscription or selected platform subscriptions.
  4. Remove temporary deployment access that isn't needed for steady-state operations.

For more information, see Post-deployment tasks for Azure landing zone for Nonprofits.

Deployment succeeds but alert response isn't ready

A deployment can succeed even when alert-response ownership still needs follow-up.

Symptom: The deployment summary or post-deployment review shows that alert-response readiness isn't complete.

Resolution:

  1. Confirm that monitoring notification emails were supplied.
  2. Use durable shared mailboxes or distribution lists instead of temporary deployment users.
  3. Confirm that service health and planned maintenance alerts route to the expected recipients.
  4. Confirm who responds to alerts and where incidents are tracked.

For more information, see Post-deployment tasks for Azure landing zone for Nonprofits.

Foundation virtual network can't reach the expanded platform hub

If you need to keep an existing foundation virtual network reachable during a transition to expanded platform, make sure you configure and connect bidirectional virtual network peering.

Resolution: Use Peer a foundation virtual network with an expanded platform hub to create and validate both peering directions.

If either peering doesn't report Connected, confirm that the virtual network IDs are correct, the address spaces don't overlap, and the operator has permission to create peerings on both virtual networks.

See also

  • Last updated on