NotFound
ARM returns `NotFound` when a deployment operation references a resource that is unavailable at evaluation time.
Last reviewed: February 19, 2026|Editorial standard: source-backed technical guidance
What Does Not Found Mean?
Deployment execution breaks on dependency resolution, so downstream resources fail until required resources are reachable at the right stage.
Common Causes
- -Template deploys dependent resources in parallel without required dependency edges.
- -Reference functions target resources not yet provisioned in the same deployment flow.
- -Cross-resource-group or cross-subscription references omit full resource IDs.
- -Target resource genuinely does not exist due to rename, deletion, or wrong scope input.
How to Fix Not Found
- 1Review deployment operations and identify which reference failed first.
- 2Add explicit or implicit dependencies so referenced resources deploy before consumers.
- 3Use full resource IDs for resources outside the current deployment scope.
- 4Re-run deployment after correcting dependency graph and scope inputs.
Step-by-Step Diagnosis for Not Found
- 1Capture failing operation details and extract the unresolved resource reference path.
- 2Inspect deployment timeline to verify whether parent or prerequisite resources were available in time.
- 3Audit
dependsOn,reference, andresourceIdusage for missing scope parameters. - 4Retest after dependency and reference corrections using validation plus full deployment replay.
Dependency Graph and Ordering Analysis
- -Trace deployment events for parallel resource creation race conditions (example: app setting references storage key before storage account deployment succeeds).
- -Add explicit
dependsOnonly where ordering is required (example: child extension resource must wait for parent VM provisioning).
Reference Function Scope Validation
- -Verify
reference()andlist*()usage across scopes (example: cross-resource-group storage reference without full resource ID returns NotFound). - -Check
existingresource declarations in Bicep include proper scope (example: resource exists in shared infra RG but template resolves current RG by default).
How to Verify the Fix
- -Run deployment again and confirm
NotFoundno longer appears in operation logs. - -Validate dependency-critical resources are created and referenced in correct order.
- -Confirm all cross-scope references resolve to expected resource IDs.
How to Prevent Recurrence
- -Encode dependency requirements directly in template design and review checklist.
- -Prefer symbolic-name references that create implicit dependencies when supported.
- -Add preflight checks for external resource existence and scope correctness.
Pro Tip
- -fail CI when dependency graph diff introduces new parallel edges touching
reference()consumers without a matching ordering guarantee.
Decision Support
Compare Guide
429 Too Many Requests vs 503 Service Unavailable
Use 429 for caller-specific throttling and 503 for service-wide outages, so retry behavior, escalation paths, and incident ownership stay correct.
Compare Guide
500 Internal Server Error vs 502 Bad Gateway: Root Cause
Debug 500 vs 502 faster: use 500 for origin failures and 502 for invalid upstream responses at gateways, then route incidents to the right team.
Playbook
API Timeout Playbook (502 / 504 / DEADLINE_EXCEEDED)
Use this playbook to separate invalid upstream responses from upstream wait expiration and deadline exhaustion, and apply timeout budgets, safe retries, and circuit-breaker controls safely.
Playbook
Availability and Dependency Playbook (500 / 503 / ServiceUnavailable)
Use this playbook to separate origin-side 500 failures from temporary 503 dependency or capacity outages, then apply safe retry and escalation paths.
Official References
Provider Context
This guidance is specific to Azure services. Always validate implementation details against official provider documentation before deploying to production.