🚨 GCP Error: 'denied: Permission artifactregistry.repositories.uploadArtifacts denied' — Cause, Fix, and Troubleshooting Guide

Overview

docker push (or gcloud, Cloud Build, npm/Maven publish) to Artifact Registry fails when the pushing identity lacks the write permission artifactregistry.repositories.uploadArtifacts:

denied: Permission "artifactregistry.repositories.uploadArtifacts" denied on
resource "projects/acme-prod-platform/locations/us/repositories/app-images"
(or it may not exist)

This is a push-side 403. It is distinct from a pull failure (ImagePullBackOff / artifactregistry.repositories.downloadArtifacts): pushing needs a writer role, and the CLI must be authenticated as an identity that holds it.

Symptoms

• docker push <region>-docker.pkg.dev/... ends in denied: Permission "...uploadArtifacts" denied.
• Cloud Build steps that push images fail on the push, though the build itself succeeds.
• gcloud auth configure-docker was never run, so Docker has no credential helper.
• Pull works but push fails for the same repo (read granted, write not).

Common Root Causes

1. Identity lacks a writer role

The user/service account has roles/artifactregistry.reader (or nothing) but not roles/artifactregistry.writer on the repo/project.

2. Docker not configured to authenticate to the registry host

gcloud auth configure-docker <region>-docker.pkg.dev was never run, so pushes go out unauthenticated.

3. Cloud Build service account missing write access

The <project-number>@cloudbuild.gserviceaccount.com (or a custom build SA) has no writer role on the target repo.

4. Wrong project/region or repo doesn’t exist

The image path targets a repo in another project/location (the message even notes “or it may not exist”).

How to Diagnose

All read-only.

# Which identity is pushing?
gcloud config get-value account
gcloud auth list

# Does that identity have write on the repo? (test-iam-permissions)
gcloud artifacts repositories get-iam-policy app-images \
  --location=us --project=acme-prod-platform \
  --flatten="bindings[].members" \
  --filter="bindings.members:$(gcloud config get-value account)" \
  --format="table(bindings.role)"

# Does the repo actually exist where the image path points?
gcloud artifacts repositories describe app-images \
  --location=us --project=acme-prod-platform \
  --format="value(name, format)"

# Is Docker configured for this registry host?
grep -A3 'pkg.dev' ~/.docker/config.json 2>/dev/null || echo "docker not configured for Artifact Registry"

No writer role in the policy, or no pkg.dev entry in Docker config, pinpoints the cause.

Fixes

Grant a writer role to the pushing identity (least privilege for CI):

gcloud artifacts repositories add-iam-policy-binding app-images \
  --location=us --project=acme-prod-platform \
  --member="serviceAccount:ci-deployer@acme-prod-platform.iam.gserviceaccount.com" \
  --role="roles/artifactregistry.writer"

Configure Docker auth for the registry host:

gcloud auth configure-docker us-docker.pkg.dev

For Cloud Build, grant its service account write access:

gcloud artifacts repositories add-iam-policy-binding app-images \
  --location=us --project=acme-prod-platform \
  --member="serviceAccount:$(gcloud projects describe acme-prod-platform \
     --format='value(projectNumber)')@cloudbuild.gserviceaccount.com" \
  --role="roles/artifactregistry.writer"

Fix the image path so region/project/repo match an existing repository.

What to Watch Out For

• Reader ≠ writer: pulling works with downloadArtifacts, but pushing needs uploadArtifacts (grant roles/artifactregistry.writer).
• Always run gcloud auth configure-docker <host> for the specific *-docker.pkg.dev host — the credential helper is host-scoped.
• The “or it may not exist” tail often means a region/project typo in the image path, not just a permission gap.
• Grant write at the repository level, not the whole project, to keep CI identities least-privilege.

Related

• GCP Error: ‘ImagePullBackOff’ Artifact Registry Forbidden
• GCP Error: ‘PERMISSION_DENIED (403)’ Caller Does Not Have Permission
• GCP Error: ‘Cloud Build timed out’
• More in the GCP error guides.