Introduction

When Docker image push to Google Cloud fails, the cause is usually authentication, repository naming, or IAM permission mismatch. The exact fix depends on whether you use legacy Container Registry (gcr.io) or Artifact Registry (*.pkg.dev).

A reliable troubleshooting sequence is: verify active account/project, configure Docker auth helper, confirm repository path, and test required IAM roles.

Core Sections

1. Verify gcloud account and project

gcloud auth list
gcloud config list project

If wrong account/project is active, push can fail even with valid credentials.

2. Configure Docker credential helper

For Artifact Registry:

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

For Container Registry:

gcloud auth configure-docker gcr.io

3. Tag image with correct repository path

docker tag myapp:latest us-central1-docker.pkg.dev/my-project/my-repo/myapp:latest
docker push us-central1-docker.pkg.dev/my-project/my-repo/myapp:latest

Wrong repo hostname or project ID causes denied/not found errors.

4. Check IAM permissions

Required roles commonly include Artifact Registry Writer or Storage-related permissions for legacy flows.

gcloud projects get-iam-policy my-project --format=json

Ensure pushing principal has repository-level access.

5. Service account in CI

In CI/CD, activate service account explicitly:

gcloud auth activate-service-account --key-file=key.json
gcloud auth configure-docker us-central1-docker.pkg.dev --quiet

Common Pitfalls

• Using Container Registry endpoints while repository actually lives in Artifact Registry.
• Forgetting to configure Docker auth helper for the target registry host.
• Tagging image with incorrect project/repository path.
• Running push under user account locally but service account in CI without equivalent permissions.
• Ignoring region-specific Artifact Registry hostname requirements.

Summary

Most gcloud Docker push failures come from auth configuration or naming mismatches. Confirm active identity/project, configure Docker credentials for correct registry host, use exact repository tag format, and verify IAM permissions. With those checks in order, pushes become predictable across local and CI environments.

A practical way to keep this guidance valuable over time is to convert it into an executable runbook rather than treating it as static prose. The runbook should include exact prerequisites, supported tool versions, expected environment settings, and a concise verification sequence that can be run from a clean machine. For each step, include a brief expected output and one common failure signature so engineers can quickly determine whether they are on a known-good path or a known-bad path. This reduces guesswork during incidents and shortens time-to-resolution when teams rotate ownership frequently.

It also helps to maintain one minimal reproducible fixture in source control for the specific scenario covered by the article. The fixture can be a tiny script, focused test case, sample dataset, or minimal manifest depending on topic. The point is to have an artifact that demonstrates both successful behavior and a realistic failure condition in isolation. When dependency versions or infrastructure behavior change, teams can run the fixture quickly and identify whether the regression is caused by environment drift, configuration mismatch, or application logic changes. This dramatically improves debugging speed compared to investigating only full production workflows.

For long-term reliability, add one lightweight CI guardrail that targets the most failure-prone step in the flow. Good examples include schema checks, startup smoke tests, deterministic unit tests, API contract assertions, and compatibility probes. Keep guardrails fast and specific so they run on every change and produce actionable failures. If a class of issue appears repeatedly, promote the manual troubleshooting step into automation so regressions are caught before deployment. Over time, this shifts effort from reactive debugging to preventive quality control and keeps operational knowledge aligned with real-world delivery practices.

As an additional safeguard, schedule periodic verification in a clean ephemeral environment and store the results as part of release evidence. This keeps assumptions current as dependencies evolve and helps detect subtle regressions before they reach production.