🚨 GCP Error Guide: 'The resource was not found (404)' Not Found Errors

Overview

A 404 not found error means Google Cloud could not locate a resource at the exact path you referenced: the combination of project, location (region/zone), and resource name did not resolve to anything the caller can see. GCP looks up the fully-qualified resource path, finds no matching object in scope, and returns HTTP 404 rather than guessing what you meant.

You will see this from gcloud or the client libraries:

ERROR: (gcloud.compute.instances.describe) Could not fetch resource:
 - The resource 'projects/my-prod-project/zones/us-central1-a/instances/web-01' was not found

Or the API/library form:

googleapi: Error 404: The resource 'projects/my-prod-project/global/networks/vpc-main' was not found, notFound

It occurs on describe/get/update/delete calls and on references inside create calls (e.g. a network or disk that does not exist in the named project/region). Because the path is project- and location-scoped, the same name can exist in another project, region, or zone and resolve fine there.

Symptoms

• describe/delete fails with The resource '<full-path>' was not found.
• A create call fails because a referenced network, subnet, disk, or service account “was not found.”
• The resource is visible in the Console but gcloud 404s (usually a project/region mismatch).
• The resource existed earlier and now 404s (deleted, or recreated elsewhere).

gcloud compute instances describe web-01 --zone us-central1-a

ERROR: (gcloud.compute.instances.describe) Could not fetch resource:
 - The resource 'projects/my-prod-project/zones/us-central1-a/instances/web-01' was not found

Common Root Causes

1. Wrong active/default project

gcloud defaults to the configured project. If that is not where the resource lives, the path resolves to nothing.

gcloud config get-value project
gcloud compute instances list --filter="name=web-01" \
  --format="table(name, zone.basename(), networkInterfaces[0].network.basename())"

my-staging-project
Listed 0 items.

The default project is my-staging-project but web-01 lives in my-prod-project; the lookup misses.

2. Wrong region or zone

Zonal/regional resources only resolve in their own location. The right name in the wrong zone is a 404.

gcloud compute instances list --filter="name=web-01" \
  --format="table(name, zone.basename())"

NAME    ZONE
web-01  us-east1-b

The instance is in us-east1-b, not the us-central1-a being queried.

3. Typo or stale name reference

A misspelled name, an old name after a rename/recreate, or a copy-pasted ID from another environment.

gcloud compute instances list --filter="name~web" \
  --format="table(name, zone.basename())"

NAME      ZONE
web-001   us-central1-a
web-002   us-central1-a

There is no web-01; the actual names are zero-padded web-001/web-002.

4. The resource was deleted (or never created)

Another process, a Terraform destroy, or a teammate removed it. Audit logs confirm.

gcloud logging read \
  'protoPayload.methodName:"compute.instances.delete" AND protoPayload.resourceName:"web-01"' \
  --project my-prod-project --limit 1 \
  --format="table(timestamp, protoPayload.authenticationInfo.principalEmail)"

TIMESTAMP                       PRINCIPAL_EMAIL
2026-06-22T19:40:03Z            terraform@my-prod-project.iam.gserviceaccount.com

A delete by the Terraform service account explains the 404 — the resource is genuinely gone.

5. A referenced dependency doesn’t exist in this project/region

Create calls fail when they point at a network, subnet, disk, or service account that isn’t where they expect it.

gcloud compute networks list --format="table(name)" --project my-prod-project

NAME
default

A create referencing vpc-main 404s because only default exists in this project — the VPC lives elsewhere.

6. Eventual-consistency / propagation lag

Immediately after creation, a resource (or an IAM/service-account binding) can briefly 404 before it is globally visible.

gcloud iam service-accounts describe \
  new-sa@my-prod-project.iam.gserviceaccount.com

ERROR: (gcloud.iam.service-accounts.describe) NOT_FOUND: Unknown service account

If the account was just created, retry after a short delay — newly created identities can lag a few seconds to a minute.

Diagnostic Workflow

Step 1: Read the full resource path in the error

The message contains the complete path: projects/<project>/zones/<zone>/instances/<name> (or global/networks/...). Compare every segment — project, location, type, name — to what you intend.

Step 2: Confirm the active project and configuration

gcloud config list

[core]
account = james@example.com
project = my-staging-project

If project is not where the resource lives, that alone explains the 404.

Step 3: Search across locations for the real resource

# Find the instance regardless of zone
gcloud compute instances list --filter="name~web-0" \
  --format="table(name, zone.basename(), status)"

# Or search a specific project explicitly
gcloud compute instances list --project my-prod-project \
  --format="table(name, zone.basename())"

This reveals the true project/zone/name to use.

Step 4: Check whether it was deleted

gcloud logging read \
  'protoPayload.methodName:"delete" AND protoPayload.resourceName:"<name>"' \
  --project my-prod-project --limit 3 \
  --format="table(timestamp, protoPayload.methodName, protoPayload.authenticationInfo.principalEmail)"

A matching delete entry means the resource is gone and must be recreated, not re-referenced.

Step 5: Re-run with the correct, fully-qualified reference

gcloud compute instances describe web-001 \
  --project my-prod-project --zone us-east1-b

Set the right project/zone (or use full --project/--zone flags) rather than relying on defaults.

Example Root Cause Analysis

A monitoring script that describes db-primary starts failing across the fleet:

ERROR: (gcloud.compute.instances.describe) Could not fetch resource:
 - The resource 'projects/my-prod-project/zones/us-central1-a/instances/db-primary' was not found

The instance shows in the Console, so it exists somewhere. Searching by name across zones:

gcloud compute instances list --project my-prod-project --filter="name=db-primary" \
  --format="table(name, zone.basename(), status)"

NAME        ZONE          STATUS
db-primary  us-central1-c RUNNING

The instance was recreated in us-central1-c during a recent maintenance migration, but the script hardcodes us-central1-a. Nothing was deleted — it simply moved zones. The audit log confirms a create in the new zone and a delete in the old one.

Fix: parameterize the zone (or look it up dynamically) instead of hardcoding it:

ZONE=$(gcloud compute instances list --filter="name=db-primary" \
  --format="value(zone.basename())")
gcloud compute instances describe db-primary --zone "$ZONE"

The describe now resolves and the monitoring script is resilient to zone changes.

Prevention Best Practices

• Always pass --project and --zone/--region explicitly in scripts and CI rather than relying on the active config, which drifts between environments.
• Reference resources by fully-qualified self-links or look them up by label/name at runtime, so renames and zone moves don’t break hardcoded paths.
• Add a short retry-with-backoff around create-then-use sequences to absorb eventual-consistency lag for freshly created resources and IAM identities.
• Manage cross-resource dependencies (networks, subnets, disks, service accounts) declaratively in the same project so a create never references something that isn’t there.
• Audit destructive automation (Terraform destroy, cleanup jobs) and require approvals so resources aren’t deleted out from under consumers.
• For triage, the free incident assistant can parse the 404 path and flag the likely project/zone mismatch. More GCP material is in the GCP guides.

Quick Command Reference

# Read the full path from the error: project / location / type / name

# Confirm active project + config
gcloud config list

# Find the resource regardless of zone/region
gcloud compute instances list --filter="name~<partial>" \
  --format="table(name, zone.basename(), status)"

# Search a specific project explicitly
gcloud compute instances list --project <PROJECT>

# Was it deleted? Check audit logs
gcloud logging read \
  'protoPayload.methodName:"delete" AND protoPayload.resourceName:"<name>"' \
  --project <PROJECT> --limit 3

# Re-run fully qualified
gcloud compute instances describe <NAME> --project <PROJECT> --zone <ZONE>

# List dependency resources in the target project
gcloud compute networks list --project <PROJECT>
gcloud iam service-accounts list --project <PROJECT>

Conclusion

A 404 not found means the project + location + name you referenced did not resolve to any resource in scope. The usual root causes:

1. The active/default project is not where the resource lives.
2. The resource is in a different region or zone than queried.
3. A typo or a stale name after a rename/recreate.
4. The resource was deleted (or never created).
5. A create call references a network/disk/service account that doesn’t exist in this project/region.
6. Eventual-consistency lag on a just-created resource or identity.

Read the full resource path in the error, confirm your active project, then search across locations for the real object — the fix is almost always correcting the project/zone reference or recreating something that was deleted.