Terraform 403 Permission Errors in GCP: Find Missing Roles Fast

What a Terraform 403 actually means

Terraform authenticates to GCP as a specific identity, either your personal Google account or a service account. Every GCP API call requires the caller to hold certain IAM permissions. When the authenticated identity is missing a required permission, GCP rejects the request with HTTP 403 and returns the exact permission it expected.

The fix always follows the same pattern:

1. Identify which identity Terraform is using
2. Read the missing permission from the error
3. Find the smallest predefined role that includes that permission
4. Grant the role at the correct scope (project, folder, or resource)

This is the same IAM model that applies to any GCP access denial. If you want a broader overview of how GCP permission errors work beyond Terraform, see Permission Denied Errors.

Fast fix checklist

Follow these steps when Terraform returns a 403. Most issues resolve in under a minute once you read the error carefully.

1. Read the error. Find the exact missing permission (e.g., storage.buckets.create) and the identity that was denied.
2. Confirm the active identity. Run gcloud auth list and check that Terraform is using the identity you expect. If using ADC, run gcloud auth application-default print-access-token and decode it.
3. Classify the problem. Is it a missing permission, wrong identity, disabled API, or org policy restriction? Each has a different fix.
4. Grant the minimal role. Look up the permission in the IAM permissions reference to find the narrowest predefined role. Grant it at the correct scope using gcloud IAM commands.
5. Re-run plan or apply. If another permission is missing, repeat from step 1.

How to read a Terraform 403 error

A typical Terraform 403 error contains four pieces of information:

Error: Error creating Bucket: googleapi: Error 403:
xxx@developer.gserviceaccount.com does not have storage.buckets.create
access to the Google Cloud project.
Required 'storage.buckets.create' permission for 'projects/my-project'.

How Terraform authenticates with GCP

The Terraform Google provider supports several credential methods. These are not the same as Google Application Default Credentials (ADC), though some of them overlap.

Terraform provider credential lookup

The google provider checks for credentials in this order:

1. The credentials field in the provider block (inline JSON or file path)
2. The GOOGLE_CREDENTIALS environment variable (JSON string)
3. The GOOGLE_APPLICATION_CREDENTIALS environment variable (path to a key file)
4. Application Default Credentials (ADC)

When the provider falls through to ADC, the standard Google ADC lookup order applies:

Google Application Default Credentials (ADC) lookup order

1. GOOGLE_APPLICATION_CREDENTIALS environment variable pointing to a credentials file
2. Local ADC file created by gcloud auth application-default login (stored at ~/.config/gcloud/application_default_credentials.json)
3. Attached service account from the metadata server (GCE, Cloud Run, GKE, Cloud Build)

Checking and setting credentials

# Check which ADC credentials are currently active
gcloud auth application-default print-access-token

# Set up ADC for local development with your personal account
gcloud auth application-default login

# Test as a service account without downloading a key file
gcloud auth application-default login \
  --impersonate-service-account=terraform@my-project.iam.gserviceaccount.com

For local development, service account impersonation lets you test with the same identity that CI/CD uses, without downloading key files. This catches permission gaps before they reach the pipeline.

For CI/CD pipelines, use Workload Identity Federation to authenticate without long-lived service account keys. GitHub Actions, GitLab CI, and most major CI providers support it. Only fall back to service account keys if your CI system has no federation support and no other option exists.

Permission denied vs wrong identity vs API not enabled vs policy deny

Not every Terraform failure is a missing role. Use this table to classify the problem before granting anything.

Common Terraform operations and the roles they need

The right role depends on what Terraform manages. Do not grant broad roles preemptively. Start with nothing extra, run terraform plan, and add roles as 403 errors identify missing permissions. This follows the principle of least privilege.

IAM resource permissions (the most common surprise)

When Terraform manages IAM resources like google_project_iam_binding or google_storage_bucket_iam_member, it needs permission to modify IAM policies. This is separate from the permission to manage the resource itself. A service account with roles/storage.admin can create buckets, but it cannot grant other identities access to those buckets unless it also has storage.buckets.setIamPolicy.

For a complete guide to managing IAM through Terraform, including the differences between member, binding, and policy resources, see Managing IAM with Terraform.

# This resource requires roles/iam.securityAdmin on the project
# because it modifies the project's IAM policy
resource "google_project_iam_binding" "viewer" {
  project = var.project_id
  role    = "roles/viewer"
  members = ["serviceAccount:${google_service_account.app.email}"]
}

• Project IAM: resourcemanager.projects.setIamPolicy, included in roles/iam.securityAdmin
• Service account IAM: iam.serviceAccounts.setIamPolicy, included in roles/iam.serviceAccountAdmin
• Bucket IAM: storage.buckets.setIamPolicy, included in roles/storage.admin

GCS backend and Terraform state bucket permission errors

If Terraform uses a GCS bucket for remote state, the authenticated identity needs object-level access to that specific bucket. This is separate from any permissions needed for the resources Terraform manages.

# backend.tf
terraform {
  backend "gcs" {
    bucket = "my-terraform-state"
    prefix = "terraform/state"
  }
}

# Grant the Terraform service account access to the state bucket
gcloud storage buckets add-iam-policy-binding gs://my-terraform-state \
  --member="serviceAccount:terraform@my-project.iam.gserviceaccount.com" \
  --role="roles/storage.objectAdmin"

roles/storage.objectAdmin on the state bucket allows Terraform to read, write, and lock the state file. A narrower role like roles/storage.objectViewer allows terraform plan (which only reads state) but blocks terraform apply (which writes state).

For more on remote state configuration, locking, and backend setup, see Terraform State Management.

When to use this guide

This page is the right starting point when:

• Terraform returns a 403 error during plan or apply
• The same Terraform config works locally but fails in CI/CD
• terraform init fails with a GCS backend access error
• Terraform can manage resources but fails when creating IAM bindings
• You are setting up a new Terraform service account and need to know which roles to start with

If Terraform is failing for reasons other than permission errors, the Terraform for Google Cloud guide covers setup, authentication, and general workflow.