🚨 GCP Error Guide: 'SERVICE_DISABLED — API has not been used in project before or it is disabled'

Exact Error Message

Calls to a Google Cloud API whose service is not enabled return a structured SERVICE_DISABLED error. A typical response from a REST call or client library looks like this:

{
  "error": {
    "code": 403,
    "message": "Cloud Run Admin API has not been used in project acme-staging-882 before or it is disabled. Enable it by visiting https://console.developers.google.com/apis/api/run.googleapis.com/overview?project=acme-staging-882 then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry.",
    "status": "PERMISSION_DENIED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "SERVICE_DISABLED",
        "domain": "googleapis.com",
        "metadata": {
          "service": "run.googleapis.com",
          "consumer": "projects/acme-staging-882"
        }
      }
    ]
  }
}

The same condition surfaces from gcloud and Terraform:

ERROR: (gcloud.run.deploy) PERMISSION_DENIED: Cloud Run Admin API has not been used
in project acme-staging-882 before or it is disabled.

What the Error Means

Every Google Cloud product is exposed as a service (for example run.googleapis.com, compute.googleapis.com, artifactregistry.googleapis.com). Before any project can call a service’s API, that service must be explicitly enabled on the project. Until then, every request — even a perfectly authenticated and authorized one — is rejected with HTTP 403 and the machine-readable reason: SERVICE_DISABLED.

The HTTP status is PERMISSION_DENIED, which is misleading: this is not an IAM permission problem. Your credentials may be entirely correct. The block is at the service activation layer, which sits in front of IAM. The metadata.service field tells you exactly which API to turn on, and metadata.consumer tells you which project it must be enabled in.

The final sentence — “wait a few minutes for the action to propagate” — is important. Enablement is eventually consistent, so the error can persist briefly even after you enable the API.

Common Causes

• The API was simply never enabled in a freshly created project.
• A new project was provisioned by Terraform/IaC that enables some APIs but not the one this call needs.
• The call targets the wrong project (wrong gcloud config project, wrong quota project, or wrong billing project on an application default credential).
• A dependency API is disabled — for example calling Cloud Run also needs artifactregistry.googleapis.com and cloudbuild.googleapis.com.
• Someone disabled the API to cut costs or during a security review, and a service later tried to use it.
• The API was enabled seconds ago and the change has not yet propagated.

How to Reproduce the Error

1. Create a brand-new GCP project: gcloud projects create acme-staging-882.
2. Link a billing account but do not enable any optional APIs.
3. Attempt an operation that depends on a non-default service, for example gcloud run deploy or a Terraform google_cloud_run_service resource.

Because the new project has only the baseline services enabled, the deploy fails immediately with SERVICE_DISABLED naming run.googleapis.com.

Diagnostic Commands

These are all read-only inspections.

# Confirm which project gcloud is actually targeting.
gcloud config get-value project

# List every service currently enabled on the project.
gcloud services list --enabled --project acme-staging-882

# Check whether the specific service is enabled (empty result = disabled).
gcloud services list --enabled --project acme-staging-882 \
  --filter="config.name=run.googleapis.com"

# Inspect the service definition and its dependencies.
gcloud services list --available --project acme-staging-882 \
  --filter="config.name:run.googleapis.com"

# See the full service config, including required APIs.
gcloud services describe run.googleapis.com --project acme-staging-882

# Confirm the project has active billing (a common blocker for enablement).
gcloud billing projects describe acme-staging-882

Step-by-Step Resolution

1. Confirm the right project. If gcloud config get-value project is wrong, the fastest fix is correcting the project, not enabling APIs everywhere:

gcloud config set project acme-staging-882

2. Enable the named service:

gcloud services enable run.googleapis.com --project acme-staging-882

3. Enable transitive dependencies that the product needs. For Cloud Run that typically means:

gcloud services enable \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  --project acme-staging-882

4. Wait for propagation. Enablement is eventually consistent — give it 1 to 5 minutes before retrying. Retrying instantly can still return SERVICE_DISABLED.

5. Retry the original operation. The deploy or API call should now succeed.

6. For Terraform, add a google_project_service resource for each required API and let Terraform manage enablement, so the dependency is encoded rather than fixed by hand each time.

Prevention and Best Practices

• Manage API enablement declaratively with google_project_service (or a project factory module) so every new project starts with the services your platform needs.
• Maintain a canonical list of “baseline” APIs your organization always enables and apply it at project creation.
• Set an explicit quota project on application default credentials so client libraries bill and check enablement against the project you intend.
• Avoid disabling APIs to save money on shared projects; disablement is blunt and breaks dependent workloads silently.
• When automating, treat the first call after enablement as retryable with backoff to absorb propagation delay.
• Wire SERVICE_DISABLED into your alerting so a missing dependency in a new environment is caught at deploy time. A structured triage flow helps here — see our incident response tooling.

Related Errors

• PERMISSION_DENIED with reason: IAM_PERMISSION_DENIED — a genuine IAM problem, distinct from service disablement despite the shared HTTP status.
• Billing account ... is disabled — many APIs cannot be enabled until billing is active.
• Cloud Resource Manager API has not been used — the meta-API needed to enable other APIs; enable it first.
• SERVICE_NOT_FOUND — the service name is misspelled or does not exist, versus existing-but-disabled.

Frequently Asked Questions

Why is the status PERMISSION_DENIED if it is not a permissions problem? Google reuses the PERMISSION_DENIED HTTP/gRPC status for service-activation failures. The authoritative signal is the reason field: SERVICE_DISABLED means enable the API, not change IAM.

I enabled the API but still get the error — what now? Enablement is eventually consistent. Wait one to five minutes and retry. If it persists, confirm you enabled it in the exact project named in metadata.consumer, not a similarly named one.

Which project does the API need to be enabled in? The one in the error’s metadata.consumer field. For client libraries this is your quota/billing project, which may differ from the resource’s project.

Do I need to enable dependency APIs separately? Often yes. Products like Cloud Run, Cloud Functions, and GKE pull in other services (Artifact Registry, Cloud Build). Enable the whole set to avoid a cascade of SERVICE_DISABLED errors.

Can I enable APIs without being an Owner? You need serviceusage.services.enable, granted by roles/serviceusage.serviceUsageAdmin (or Owner/Editor). A least-privilege role exists precisely so you do not have to hand out Owner.

Why did an API that used to work suddenly start failing? Someone likely disabled it, or your tooling switched to a different project where it was never enabled. Check the project in the error and the service’s enablement state. More patterns are in our GCP guides.