ImageNotFound
Azure returns `ImageNotFound` when the VM image reference cannot be resolved for the selected region, subscription, or source registry.
Last reviewed: February 26, 2026|Editorial standard: source-backed technical guidance
What Does Image Not Found Mean?
VM creation is blocked at image resolution, so provisioning cannot begin until a valid and accessible image source is selected.
Common Causes
- -Publisher/offer/sku/version tuple is incorrect, deprecated, or misspelled.
- -Requested image is unavailable in the target region or zone.
- -Marketplace image terms were not accepted for the subscription.
- -Shared Image Gallery or custom image resource was moved, deleted, or access-restricted.
How to Fix Image Not Found
- 1Query image availability in the target region and replace stale image reference values.
- 2Confirm marketplace plan and terms acceptance for the exact image offer.
- 3Validate deployment identity can read the image source (gallery, managed image, or marketplace).
- 4Pin known-good image versions in release manifests before deployment.
Step-by-Step Diagnosis for Image Not Found
- 1Capture the exact image reference used in the failing deployment operation.
- 2Verify regional availability for the requested image version and architecture.
- 3Check source image permissions and subscription context for the deploying principal.
- 4Retest with a verified image reference from a successful baseline deployment.
Image Reference Integrity Checks
- -Audit each reference component (publisher, offer, sku, version) for typos and deprecations (example: template pins retired SKU alias no longer published in target region).
- -Validate image ID path for gallery/custom images (example: reference points to old gallery version removed during cleanup).
Marketplace and Access Prerequisite Validation
- -Confirm marketplace terms acceptance state per subscription (example: new subscription missing terms acceptance for hardened base image).
- -Inspect image-source RBAC access (example: deployment principal can create VMs but lacks read on shared image gallery).
How to Verify the Fix
- -Rerun deployment and confirm
ImageNotFoundno longer appears. - -Validate VM provisioning starts with the intended image source and version.
- -Ensure repeat deployments use the same resolvable image manifest consistently.
How to Prevent Recurrence
- -Maintain approved image catalog per region with automated availability checks.
- -Version-lock image references and validate them in CI before release.
- -Alert on image deprecation notices that impact production templates.
Pro Tip
- -run a daily canary deployment per critical region that resolves all production image references and fails fast on drift.
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.