SubscriptionNotFound
ARM returns `SubscriptionNotFound` when the deployment subscription cannot be accessed due to wrong subscription ID, format, or insufficient access.
Last reviewed: February 5, 2026|Editorial standard: source-backed technical guidance
What Does Subscription Not Found Mean?
Deployment orchestration fails at scope resolution, so no resource operation can proceed until the subscription context is corrected.
Common Causes
- -Provided subscription ID is wrong, malformed, or not the intended target.
- -Deploying principal lacks access to the specified subscription.
- -Nested or cross-scope deployment omits or uses incorrect subscription GUID.
- -Automation runs in a different default subscription context than expected.
How to Fix Subscription Not Found
- 1Validate subscription GUID and ensure it matches the intended deployment target.
- 2Check caller role assignments on the target subscription scope.
- 3For nested or cross-scope deployments, pass explicit subscription GUID in template parameters.
- 4Set subscription context explicitly in CLI or PowerShell before running deployment.
Step-by-Step Diagnosis for Subscription Not Found
- 1Capture deployment error payload and identify the exact subscription value used.
- 2Run account context commands to verify active tenant/subscription on the execution host.
- 3Inspect nested deployment scopes and parameter flow for subscription ID drift.
- 4Re-run deployment with explicit subscription setting after access validation.
Subscription Context and Access Validation
- -Verify active context with CLI/PowerShell before deployment (example: runner defaults to sandbox subscription while template expects production).
- -Check principal access at subscription scope (example: principal has resource-group permissions in another subscription only).
Cross-Scope Deployment Parameter Checks
- -Audit nested deployment parameters for explicit subscription GUID propagation (example: template passes display name instead of GUID).
- -Validate subscription format and tenant association in configuration sources (example: copied subscription ID includes hidden whitespace or wrong tenant mapping).
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.
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.
Pro Tip
- -bind deployment environments to immutable subscription manifests and reject runtime overrides that are not in the approved manifest.
Decision Support
Compare Guide
HTTP 400 vs 422: Bad Request vs Unprocessable Content
Fix API payload issues faster by using 400 for malformed syntax and 422 for semantic validation failures, so clients correct format before business rules.
Playbook
CORS Error Fix Playbook (Preflight / Origin / Credentials)
Use this playbook to separate browser-enforced cross-origin policy failures from server-side CORS header and route defects and apply strict origin and credential controls safely.
Playbook
Validation Failure Playbook (400 / 422 / INVALID_ARGUMENT)
Use this playbook to separate malformed-request failures from semantic validation failures, then fix request contracts without broad server-side bypasses.
Official References
Provider Context
This guidance is specific to Azure services. Always validate implementation details against official provider documentation before deploying to production.