GCP Error Codes
Google Cloud Platform error codes and exceptions
Aborted: Concurrency Conflict
ABORTED surfaces when GCP aborts your operation due to a concurrency conflict—another operation modified the resource between your read and write, triggering optimistic concurrency control. This server-side error happens when GCP detects state changes during concurrency validation in the control plane or backend. Most common in Compute Engine when multiple processes update VMs simultaneously, but also appears in Cloud SQL during concurrent database modifications, GKE during parallel cluster updates, and BigQuery when multiple clients modify tables at once. Usually transient—reading fresh resource state and retrying with exponential backoff typically resolves conflicts.
Already Exists: Resource Name Conflict
ALREADY_EXISTS hits when you're trying to create a resource with a name that's already taken in the same project and region/zone scope. This client-side error means GCP enforces name uniqueness—your chosen name conflicts with an existing resource. Most common in Compute Engine when creating VMs, disks, or networks, but also appears in Cloud SQL database instances, GKE cluster names, and BigQuery dataset names. Resource names are scoped per zone for Compute Engine, per region for Cloud SQL, and per project for GKE clusters. Recently deleted resources may still reserve names during deletion grace periods.
Cancelled: Operation Terminated
CANCELLED means the operation was terminated before completion—either you explicitly cancelled it, a client timeout killed it, or GCP's system cancelled it due to resource constraints. This can be client-side (user cancellation, timeout) or server-side (system cancellation). Most common in Compute Engine when VM operations get cancelled, but also appears in Cloud SQL during cancelled database operations, GKE during cancelled cluster operations, and BigQuery when queries are cancelled. Unlike ABORTED (which indicates concurrency conflicts), CANCELLED means intentional or automatic termination—operations that exceed timeouts or get manually stopped return this error.
Data Loss: Unrecoverable Data Corruption
DATA_LOSS indicates unrecoverable data corruption or permanent loss—GCP's backend storage systems detected integrity failures that can't be fixed automatically. This critical server-side error means data is corrupted, lost, or damaged beyond recovery. Most common in Compute Engine when disks suffer storage failures or corruption, but also appears in Cloud SQL with database corruption, GKE with persistent volume corruption, and BigQuery with table data corruption. This is a permanent issue—you must restore from backups or snapshots if available, or contact GCP support for recovery assistance.
Deadline Exceeded: Operation Timeout
DEADLINE_EXCEEDED means your operation exceeded its timeout—either your client timeout is too short for large VM creation or disk operations, or GCP's backend is slow. This can be client-side (timeout too aggressive) or server-side (backend processing delays). Most common in Compute Engine when creating large VMs or performing disk snapshots, but also surfaces in Cloud SQL during long database migrations, GKE during cluster provisioning, and BigQuery with complex long-running queries. GCP enforces timeouts to prevent indefinite hangs—operations that take longer than the allowed duration get cancelled.
Failed Precondition: System State Mismatch
FAILED_PRECONDITION means the system state blocks your operation—trying to stop an already-stopped VM, modifying a Cloud SQL database during backup, scaling a GKE cluster mid-upgrade, or querying a BigQuery table being deleted. This can be client-side (wrong resource state, missing prerequisites) or transient server-side (dependency not ready, resource locked by another operation). Most common in Compute Engine when operating on resources in wrong states, but also appears in Cloud SQL during maintenance windows, GKE during cluster operations, and BigQuery during table mutations. GCP locks resources during operations to prevent concurrent modifications.
Internal Error: System Failure
INTERNAL means GCP's backend systems hit an unexpected failure—system invariants broke, indicating a platform bug or infrastructure issue, not your request. This server-side error happens in GCP's control plane or backend services. Most common in Compute Engine during VM provisioning or disk operations, but also surfaces in Cloud SQL database operations, GKE cluster management, and BigQuery query execution. Usually transient—exponential backoff retries often succeed once GCP recovers, but persistent cases require waiting for Google to fix the underlying issue.
Invalid Argument: Parameter Validation Failure
INVALID_ARGUMENT means your request parameters failed GCP's validation—missing required fields, wrong data types (string instead of integer), or values that break constraints. This client-side error happens in the control plane before operations start. Most common in Compute Engine when using invalid zones, unsupported machine types, or disk size violations, but also surfaces in Cloud SQL with invalid database versions or regions, GKE with malformed node pool configs, and BigQuery with SQL syntax errors or schema mismatches. GCP validates parameter types strictly—passing "123" as a string when an integer is required will fail.
Invalid Request: Malformed Request Format
INVALID_REQUEST means your request format is broken—malformed JSON, unclosed brackets, missing required fields, or parameters in wrong formats. This client-side error happens during request parsing in the control plane before GCP validates parameter values. Most common in Compute Engine with malformed API requests, but also appears in Cloud SQL with invalid database configuration structures, GKE with malformed cluster configs, and BigQuery with invalid query syntax. Unlike INVALID_ARGUMENT (which indicates wrong parameter values), INVALID_REQUEST means the request structure itself is invalid—GCP can't parse it.
Invalid State: Resource State Mismatch
INVALID_STATE means the resource is in a state that blocks your operation—trying to stop an already-stopped VM, delete a resource mid-creation, or modify a Cloud SQL database during backup. This can be client-side (wrong resource state) or server-side (resource locked by another operation). Most common in Compute Engine when operating on VMs in wrong states, but also appears in Cloud SQL during maintenance windows, GKE during cluster upgrades (RECONCILING state), and BigQuery when querying tables being deleted. GCP validates resource states before operations—state machines vary by service, and some transitions require intermediate steps.
Not Found: Resource Does Not Exist
Seeing NOT_FOUND tells you GCP couldn't locate the resource—wrong resource name, ID, or path; the resource was deleted; or you're querying the wrong project, region, or zone. This client-side error happens during resource lookup in the control plane. Resource identifiers are case-sensitive and must match exactly. Most common in Compute Engine when referencing VMs, disks, or networks, but also surfaces in Cloud SQL database instances, GKE clusters and node pools, and BigQuery datasets and tables. Some services support soft-delete with recovery windows, but timing varies.
Out of Range: Parameter Value Violation
OUT_OF_RANGE means your parameter value breaches GCP's allowed bounds—disk size exceeds maximum (64 TB) or is below minimum (10 GB), port numbers outside 1-65535, or array indices beyond valid bounds. This client-side error happens during parameter validation in the control plane. Most common in Compute Engine with disk sizes and port numbers, but also surfaces in Cloud SQL with storage size limits and backup retention days, GKE with node pool and cluster size constraints, and BigQuery with query size limits. Range limits vary by service and resource type—standard disks have different limits than SSDs, and Cloud SQL tier limits differ by instance size.
Permission Denied: IAM Authorization Failure
Hitting PERMISSION_DENIED means your authenticated identity got past login but lacks the IAM role or permission GCP requires for this operation. This server-side authorization failure happens in GCP's control plane—your credentials are valid, but GCP evaluated your request and blocked it. You'll see this most often in Compute Engine VM operations, but it also surfaces in Cloud SQL database management, GKE cluster operations, and BigQuery dataset access. IAM role assignments can take 30-60 seconds to propagate, so recent grants might not be active yet.
Quota Exceeded: Resource Limit Reached
QUOTA_EXCEEDED hits when you've maxed out your project or regional quota for a resource type—GCP's control plane enforces hard limits per project and per region. This server-side error means you've hit the ceiling for VM instances, disks, Cloud SQL instances, GKE clusters, or BigQuery query quotas. Most common in Compute Engine when you've created the maximum allowed VMs or disks, but also appears in Cloud SQL instance quotas, GKE cluster and node quotas, and BigQuery query and storage quotas. Quota exhaustion is persistent until you delete unused resources or request increases via Cloud Console—unlike RESOURCE_EXHAUSTED, this specifically indicates quota limits, not capacity stockouts.
Resource Exhausted: Quota or Capacity Limit Reached
RESOURCE_EXHAUSTED hits when you've maxed out quotas (project or regional limits), hit a temporary capacity stockout in that zone, or exhausted disk space. This can be client-side (you've used all your quota) or server-side (GCP temporarily lacks capacity). Most common in Compute Engine when you've hit VM instance quotas, disk quotas, or regional capacity limits, but also appears in Cloud SQL instance and storage quotas, GKE cluster and node quotas, and BigQuery query and storage quotas. Regional stockouts are transient—try different zones or retry later. Quota exhaustion is persistent until you free resources or request increases.
Unauthenticated: Missing or Invalid Credentials
UNAUTHENTICATED means GCP can't validate your credentials—either your request has no auth credentials, your service account key is expired or revoked, or the GOOGLE_APPLICATION_CREDENTIALS environment variable isn't set. This client-side error happens before GCP even checks permissions. Most common in Compute Engine API calls, but also appears in Cloud SQL database connections, GKE cluster API access, and BigQuery query execution. OAuth tokens expire after about an hour, while service account keys don't expire by default unless revoked.
Unavailable: Service Temporarily Down
UNAVAILABLE hits when GCP's service is temporarily down—planned maintenance, traffic overload, or unplanned regional outages prevent the backend from processing requests. This server-side error means GCP's infrastructure is the problem, not your request. Most common in Compute Engine when APIs go down or regions experience outages, but also appears in Cloud SQL during connection failures, GKE when cluster APIs are unavailable, and BigQuery when query services are overloaded. Usually transient—exponential backoff retries typically succeed once service recovers, but regional outages may require switching zones.
Unimplemented: Operation Not Supported
UNIMPLEMENTED surfaces when the operation you're calling doesn't exist, isn't enabled for your project, or isn't available in your API version, region, or service tier. This client-side error happens during operation validation in the control plane. Most common in Compute Engine when using alpha/beta features without the right API version, or when machine types aren't available in that zone. Also appears in Cloud SQL with unsupported database engine versions or regional features, GKE with unavailable Kubernetes versions or regional capabilities, and BigQuery with SQL functions not supported in your region. Alpha and beta features require gcloud alpha or gcloud beta commands, not the stable API.