NOT_FOUND
GCP NOT_FOUND means the target entity cannot be resolved in the requested project, location, parent collection, or service-specific resource namespace.
Last reviewed: April 29, 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 Not Found Mean?
The API could not resolve the resource identity supplied by the client. In Google APIs, NOT_FOUND is about the requested entity or collection member not existing in the specified scope. Some services may also use not-found behavior when a resource is intentionally hidden from an entire class of users, so the useful boundary is full resource name, project, location, parent hierarchy, lifecycle state, and caller visibility.
Common Causes
- -Request uses a stale resource name from a previous deployment, project, folder, or environment.
- -Project ID/number, region, zone, location, parent, collection, or service endpoint does not match where the resource exists.
- -Resource was deleted, recreated, moved, or replaced and downstream config still holds the old name.
- -Create-then-use workflow races a child operation before parent visibility or service propagation completes.
- -Caller is using a credential or endpoint that targets a different project boundary than expected.
How to Fix Not Found
- 1Extract the exact resource name, project, location, and method from the failing request and verify them together.
- 2Run the matching
gcloud describe/listor service-specific get call in the same project and location. - 3Regenerate fully qualified resource names from live inventory or deployment outputs instead of cached IDs.
- 4Validate parent resources before child operations and add a bounded wait only for known post-create propagation windows.
- 5If the same caller cannot list the resource but an admin can, compare IAM visibility and hidden-resource behavior before assuming deletion.
Step-by-Step Diagnosis for Not Found
- 1Capture full request URI, method, resource name, project ID/number, location, parent, caller identity, request ID, and structured error details.
- 2Query resource existence with service-specific get/list APIs in the exact same project and location as the failing request.
- 3Compare failing names with Terraform state, deployment outputs, Config Connector status, service inventory, and recent audit logs.
- 4Inspect rollout events for delete/recreate, move, rename, blue/green replacement, or delayed parent creation.
- 5Retest after replacing cached resource names with fresh discovery output from the control plane.
Seen in Production
- -A Cloud Run deploy uses a service account name from staging while the production project has a different service account ID.
- -A BigQuery job targets a dataset in
USwhile the table was created in a regional dataset elsewhere. - -A Pub/Sub subscription binding runs before the topic exists or before topic creation is visible.
- -Terraform replaces a resource and downstream services keep the old full resource name in environment variables.
Resource Name and Hierarchy Validation
- -Audit fully qualified resource paths for service-specific format rules, including
projects/{project},locations/{location}, parents, and collection names. - -Verify parent-child hierarchy exists before nested operations, especially topics/subscriptions, datasets/tables, services/revisions, and policies on child resources.
Lifecycle and Visibility Checks
- -Trace resource lifecycle events for deletion, recreation, move, rename, or replacement drift.
- -Differentiate true absence from visibility boundaries where a service intentionally hides resources from a caller class.
Decision Shortcut: Missing vs Permission vs State
- -If the resource exists for another caller but this caller cannot access it, compare PERMISSION_DENIED and service-specific hidden-resource behavior.
- -If the parent exists but lifecycle state blocks the action, inspect FAILED_PRECONDITION.
- -If a create operation races with an existing name, inspect ALREADY_EXISTS rather than NOT_FOUND.
Wrong Fix to Avoid
- -Do not retry indefinitely when the resource name is stale or scoped to the wrong project.
- -Do not hand-edit only the last path segment while leaving project, location, or parent wrong.
- -Do not broaden IAM until the exact resource identity has been proven to exist in the requested scope.
Implementation Examples
{
"method": "google.cloud.run.v2.Services.GetService",
"name": "projects/prod-123/locations/us-central1/services/api-old",
"status": "NOT_FOUND",
"requestId": "9d2f3c1a7b6e4f01"
}gcloud config get-value project
gcloud run services describe api \
--project prod-123 \
--region us-central1 \
--format='value(metadata.name,status.url)'const serviceName = [
'projects', outputs.projectId,
'locations', outputs.region,
'services', outputs.cloudRunService,
].join('/');
await client.getService({ name: serviceName });Incident Timeline
14:02 UTC
Client builds a fully qualified resource name
Signal: Application config, Terraform output, service discovery, or deployment template emits project/location/parent/name.
Why it matters: The full name, not just the short ID, is what Google APIs resolve.
14:03 UTC
API returns NOT_FOUND
Signal: The target entity is absent or not visible in the requested scope.
Why it matters: The next step is scope and inventory verification before retry strategy.
14:09 UTC
Inventory shows scope or lifecycle drift
Signal: Resource exists in another project/location, was replaced, or parent creation has not completed.
Why it matters: The request path must be rebuilt from current inventory or dependency ordering fixed.
14:22 UTC
Fresh resource name is deployed
Signal: Client uses updated project/location/parent/name and dependent calls resolve successfully.
Why it matters: Prevent recurrence by treating full resource names as generated outputs, not hand-built strings.
Seen in Production
Regional rollout uses stale resource path from previous environment
Frequency: common
Example: Job targets us-central1 resource path while actual resource exists in europe-west1.
Fix: Regenerate fully qualified name from active environment metadata and redeploy.
Parallel deploy triggers child operation before parent is visible
Frequency: rare
Example: Immediate IAM binding call fails because target resource creation has not propagated yet.
Fix: Enforce dependency ordering and short bounded wait for post-create visibility.
Wrong Fix vs Better Fix
Retry stale name vs refresh discovery
Wrong fix: Keep retrying the same request path with exponential backoff.
Better fix: Fetch current inventory in the same scope and rebuild the full resource name.
Why this is better: NOT_FOUND is deterministic when the resource path points to the wrong identity.
Short ID fix vs full name fix
Wrong fix: Change only the resource short name in config.
Better fix: Validate project, project number, location, parent collection, and resource ID together.
Why this is better: Google APIs commonly require service-specific fully qualified names.
Permission broadening vs identity proof
Wrong fix: Grant broad roles before confirming the resource exists in the requested scope.
Better fix: First prove existence with an admin lookup, then compare caller visibility and required permissions.
Why this is better: This separates true absence from hidden-resource or permission behavior.
Debugging Tools
- -Cloud Audit Logs request/response traces
- -gcloud list/describe commands for same project and location
- -Deployment logs and change history
- -Resource Manager and service-specific inventory queries
- -Terraform, Config Connector, or deployment output diff
How to Verify the Fix
- -Re-run the same API call and confirm the resource resolves without NOT_FOUND.
- -Validate downstream steps complete successfully using refreshed full resource names.
- -Compare runtime config, deployment outputs, and control-plane inventory for the same project/location scope.
- -Run a dependency-order test that proves child operations wait for parent resources and propagation windows.
How to Prevent Recurrence
- -Generate full resource names centrally and avoid hand-built string paths in application code.
- -Add preflight existence checks for critical parent resources in deployment pipelines.
- -Expire cached resource names after create, move, recreate, or blue/green replacement operations.
- -Store project ID, project number, location, parent, and full name together in deployment outputs.
Pro Tip
- -persist both project number and project ID in generated resource references to catch subtle cross-project routing bugs early.
Decision Support
Official References
Provider Context
This guidance is specific to GCP services. Always validate implementation details against official provider documentation before deploying to production.