Troubleshoot container image issues

Learn about troubleshooting steps that you might find helpful if you run into problems managing container images in Artifact Registry.

Cannot pull an image or deploy to a Google Cloud runtime environment

Check the following:

1. Verify that the full path of the image that you are pushing is correct. The path must include the registry hostname, Google Cloud, project ID, repository, and image. For example:

   us-west1-docker.pkg.dev/my-project/my-repo/my-image:v1

   For more information, see Repository and image names.
2. Verify that the account that is pulling the image has the correct permissions to read from the repository. If you have disabled automatic role granting to service accounts, then you must grant Artifact Registry roles to the runtime service accounts.
• For Compute Engine, Cloud Run, and Google Kubernetes Engine service accounts, you must grant the Artifact Registry Reader role (roles/artifactregistry.reader) to the runtime service account.
• For your Cloud Build service account, you must grant the Artifact Registry Writer role (roles/artifactregistry.writer) to the service account that runs builds.
• If you are using Docker or another third-party tool, you must:
  • Grant permissions to the account that interacts with the repository.
  • Configure the client to authenticate to the repository.
    • Docker authentication instructions
    • Troubleshooting containerd node images on Google Kubernetes Engine

Cannot push an image to Artifact Registry

Try the following:

1. Verify that the repository exists. Unlike Container Registry, repository creation is a separate operation from pushing the first image. If the repository does not exist, then create it.
2. Verify that the full path of the image that you are pushing is correct. The path must include the registry hostname, Google Cloud project ID, repository, and image. For example:

   us-west1-docker.pkg.dev/my-project/my-repo/my-image:v1
     

   Each Artifact Registry repository is a separate resource, so you cannot push an image to a path without a repository. For example, us-west1-docker.pkg.dev/my-project/my-image:v1 is an invalid image path.

   For more information, see Repository and image names.

3. Verify that the account that is pushing the image has permissions to write to the repository. If you have disabled automatic role granting to service accounts, then you must grant Artifact Registry roles to the runtime service accounts.
• For Compute Engine, Cloud Run, and Google Kubernetes Engine service accounts, you must grant the Artifact Registry Writer role (roles/artifactregistry.writer) to the runtime service account.
• For your Cloud Build service account, you must grant the Artifact Registry Writer role (roles/artifactregistry.writer) to the service account that runs builds.
4. If Artifact Registry returned the message The repository has enabled tag immutability, then tag immutability is configured for the repository. You cannot push an image with a tag that is already used for another version of the same image in the repository. Try to push the image again with a tag that is not used by other stored versions of the image.

   To verify that the a repository is configured for immutable image tags, check the Immutable image tags column in the list of repositories in Google Cloud console or run the following command:

   gcloud artifacts repositories describe REPOSITORY \
         --project=PROJECT-ID \
         --location=LOCATION
     

ImagePullBackOff and ErrImagePull messages

Messages with ImagePullBackOff and ErrImagePull indicate that an image cannot be pulled from the registry by GKE.

• Verify the requirements to pull from Artifact Registry.
• Review Troubleshoot image pulls in the GKE documentation.