SubscriptionNotFound
Azure SubscriptionNotFound means ARM cannot resolve the target subscription in the caller tenant, context, deployment scope, or access graph used by the request.
Last reviewed: May 5, 2026|Source-backed guidance under our editorial policy
Start Here
Use the closest compare guide, playbook, or adjacent error page to narrow the decision faster before you start changing production systems.
This page is part of the Error Reference library. Learn more about the project or report a correction.
What Does Subscription Not Found Mean?
Azure failed before resource evaluation because the subscription scope could not be resolved. The subscription may be wrong, inaccessible to the caller, associated with another tenant, disabled, or replaced by a pipeline context default. The useful boundary is scope identity: subscription GUID, tenant, active CLI/PowerShell context, service principal access, nested deployment parameters, and whether the subscription exists but is hidden by access or tenant mismatch.
Common Causes
- -Provided subscription ID is wrong, malformed, copied with hidden characters, or not the intended environment target.
- -Deploying principal is authenticated to the wrong tenant or lacks any visible access to the specified subscription.
- -Nested, management-group, tenant, or cross-scope deployment omits or misroutes the subscription GUID.
- -CI/CD runner defaults to a sandbox or previous subscription after login or context reuse.
- -Subscription was moved, disabled, renamed in inventory, or replaced in environment mapping without updating deployment manifests.
How to Fix Subscription Not Found
- 1Validate the subscription GUID format and compare it with the approved environment manifest.
- 2Confirm active tenant and subscription context in the same shell or runner that executes deployment.
- 3Check whether the service principal can list or access the subscription at all before debugging resource templates.
- 4Pass explicit subscription IDs through nested and cross-scope deployment parameters.
- 5Reset CLI/PowerShell context explicitly before deployment and fail if context does not match target.
Step-by-Step Diagnosis for Subscription Not Found
- 1Capture correlation ID, tenant ID, caller object/app ID, command context, and the exact subscription value used.
- 2Run account context commands on the execution host after login and immediately before deployment.
- 3Inspect nested deployment scopes, Bicep modules, parameter files, and environment manifests for subscription ID drift.
- 4Validate the principal has at least visibility/access to the target subscription scope.
- 5Re-run deployment only after tenant, subscription, and access checks match the intended environment.
Seen in Production
- -A GitHub Actions runner logs into the right tenant but keeps the default sandbox subscription.
- -A management-group deployment passes a display name or empty parameter where a subscription GUID is required.
- -A service principal has resource-group access in dev but no subscription visibility in production.
- -An environment migration changes the subscription mapping, but an old variable group remains active.
Subscription Context and Access Validation
- -Verify active CLI or PowerShell tenant and subscription context immediately before deployment.
- -Check principal visibility and role assignments at the target subscription scope.
Cross-Scope Deployment Parameter Checks
- -Audit nested deployment parameters for explicit subscription GUID propagation.
- -Validate subscription format, tenant association, and environment mapping in configuration sources.
Decision Shortcut: Wrong ID, Wrong Tenant, or No Visibility
- -If the GUID is malformed or not in the environment manifest, fix the deployment input.
- -If the GUID exists but not under the active tenant, fix tenant authority and login context.
- -If the tenant is correct but the principal cannot list/access the subscription, fix access before template logic.
Wrong Fix to Avoid
- -Do not debug ARM resource properties before subscription scope resolves.
- -Do not rely on CLI default subscription in shared runners.
- -Do not use subscription display names as stable deployment identifiers.
Implementation Examples
2026-05-05T07:13:44Z deployment=prod-api tenant=72f988bf-0000-0000-0000-2d7cd011db47
expectedSubscription=11111111-2222-3333-4444-555555555555
activeSubscription=99999999-aaaa-bbbb-cccc-dddddddddddd
status=Failed error=SubscriptionNotFound correlationId=91d1d42f-1111-4444-9999-72f904000000TARGET_SUBSCRIPTION_ID="11111111-2222-3333-4444-555555555555"
az account set --subscription "$TARGET_SUBSCRIPTION_ID"
ACTIVE_SUBSCRIPTION_ID="$(az account show --query id --output tsv)"
test "$ACTIVE_SUBSCRIPTION_ID" = "$TARGET_SUBSCRIPTION_ID"az account list \
--query "[?id=='$TARGET_SUBSCRIPTION_ID'].{id:id,name:name,tenantId:tenantId,state:state}" \
--output tableIncident Timeline
07:12 UTC
Pipeline selects Azure deployment scope
Signal: Runner logs in and resolves tenant, subscription, and parameterized deployment target.
Why it matters: Context selection is part of the deployment artifact.
07:13 UTC
ARM returns SubscriptionNotFound
Signal: Resource Manager cannot resolve the subscription for the caller and request scope.
Why it matters: No resource template property is evaluated until subscription scope is valid.
07:20 UTC
Context drift is identified
Signal: Account context, parameter file, or access check shows wrong GUID, wrong tenant, or invisible subscription.
Why it matters: Fix scope identity before redeploying.
07:34 UTC
Deployment scope is pinned
Signal: Pipeline fails fast unless active context matches the approved subscription manifest.
Why it matters: Explicit scope gates prevent silent default-subscription drift.
Seen in Production
Deployment pipeline defaults to old subscription after environment migration
Frequency: common
Example: Template deploy command references retired subscription and fails before resource evaluation.
Fix: Pin subscription GUID per environment and enforce context check before each deploy stage.
Cross-scope nested deployment omits subscription GUID parameter
Frequency: rare
Example: Child deployment resolves wrong scope and returns SubscriptionNotFound.
Fix: Pass explicit subscription GUID for each nested scope in deployment parameters.
Wrong Fix vs Better Fix
Template debugging vs scope resolution
Wrong fix: Edit resource templates after seeing SubscriptionNotFound.
Better fix: Validate tenant, subscription GUID, and caller visibility first.
Why this is better: The deployment has not reached resource evaluation yet.
Default context vs explicit context
Wrong fix: Trust whatever subscription the CLI selected after login.
Better fix: Run explicit az account set or PowerShell context selection and verify it.
Why this is better: Shared runners and reused sessions commonly retain the wrong subscription.
Display name vs GUID
Wrong fix: Pass subscription display names through nested deployments.
Better fix: Pass immutable subscription GUIDs from an approved environment manifest.
Why this is better: Display names are not stable unique deployment identifiers.
Debugging Tools
- -az account show / az account set
- -Az PowerShell Set-AzContext
- -ARM deployment operation logs
- -Subscription access audit reports
How to Verify the Fix
- -Rerun the same deployment and confirm
SubscriptionNotFoundno longer appears. - -Verify deployment operations execute under the intended subscription in Activity Log.
- -Confirm nested deployment stages inherit the corrected subscription scope.
- -Confirm preflight checks fail if active context differs from the target manifest.
How to Prevent Recurrence
- -Require explicit subscription ID inputs in all deployment pipelines and scripts.
- -Add preflight access checks for deployment principals at target subscription scope.
- -Validate nested deployment scope parameters with schema and GUID-format checks.
- -Store environment-to-subscription mappings in versioned manifests instead of mutable runner defaults.
Pro Tip
- -bind deployment environments to immutable subscription manifests and reject runtime overrides that are not in the approved manifest.
Official References
Provider Context
This guidance is specific to Azure services. Always validate implementation details against official provider documentation before deploying to production.