NOT_FOUND
GCP NOT_FOUND means the requested entity cannot be resolved in the specified project, location, or parent resource namespace.
Last reviewed: February 5, 2026|Editorial standard: source-backed technical guidance
What Does Not Found Mean?
The API cannot resolve the target resource identity, so dependent operations stop until naming, scope, or lifecycle mismatches are corrected.
Common Causes
- -Resource name, ID, or URI path is malformed, stale, or built from outdated configuration.
- -Request uses the wrong project, region, zone, or parent collection in the resource hierarchy.
- -Resource was deleted, recreated under a new identifier, or never provisioned in this environment.
- -Create and read operations are racing, causing temporary lookup misses before consistency settles.
How to Fix Not Found
- 1Extract the exact resource name from the error payload and verify it in the same project and location.
- 2Rebuild request paths using fully qualified resource names from authoritative inventory sources.
- 3Validate parent-resource existence and dependency ordering before child operations.
- 4Use bounded retries only for expected post-create propagation windows, not for permanently missing resources.
Step-by-Step Diagnosis for Not Found
- 1Capture full request URI, resource name, project ID/number, and location parameters from the failing call.
- 2Query resource existence with service-specific get/list APIs in the exact same scope.
- 3Inspect recent deployment logs for rename, delete, move, or recreation events that changed identifiers.
- 4Retest after replacing cached IDs with fresh discovery output from control-plane inventory.
Resource Name and Hierarchy Validation
- -Audit fully qualified resource paths for service-specific format rules (example: missing
locations/{region}segment in request name). - -Verify parent-child hierarchy exists before nested operations (example: API call references dataset table before dataset creation completed).
Lifecycle and Visibility Checks
- -Trace resource lifecycle events for deletion or recreation drift (example: Terraform replaced resource and generated new canonical ID).
- -Differentiate true absence from rollout masking patterns (example: undocumented feature allowlist can intentionally surface NOT_FOUND for hidden resources).
How to Verify the Fix
- -Re-run the same API call and confirm the resource is resolved without NOT_FOUND.
- -Validate downstream dependent steps complete successfully using refreshed identifiers.
- -Compare inventory snapshots to ensure runtime and control-plane views are now consistent.
How to Prevent Recurrence
- -Generate resource names centrally and avoid hand-built string paths in application code.
- -Add preflight existence checks for critical parent resources in deployment pipelines.
- -Expire or invalidate cached resource IDs after create, move, or recreate operations.
Pro Tip
- -persist both project number and project ID in generated resource URIs to catch subtle cross-project routing bugs early.
Decision Support
Compare Guide
403 Forbidden vs 404 Not Found: When to Hide Resources
Use 403 for explicit access denial, or 404 to conceal resource existence when security policy requires reducing endpoint and object enumeration risk.
Compare Guide
404 Not Found vs 410 Gone: Missing vs Permanent Removal
Learn when to return 404 (missing or temporary absence) versus 410 (intentional permanent removal), including redirect and cache implications.
Playbook
Resource State Playbook (404 / 410 / ResourceNotFound)
Use this playbook to separate temporary missing-resource lookups from permanent removals, then fix scope, lifecycle, and identifier drift safely.
Official References
Provider Context
This guidance is specific to GCP services. Always validate implementation details against official provider documentation before deploying to production.