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:

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-east1-docker.pkg.dev/my-project/my-repo/my-image:v1
```
For more information, see Repository and image names.
Verify that the account that is pulling the image has permissions to read from the repository.
- The Cloud Build default service account has read and write permissions to repositories in the same Google Cloud project. If you are using a user-provided service account or pushing and pulling images across projects, grant the Artifact Registry Writer role to the service account that runs builds.
- By default Compute Engine, Cloud Run, and Google Kubernetes Engine have read permissions for repositories in the same project. If Artifact Registry is in a different project than the runtime environment, you must grant the Artifact Registry Reader role to the runtime service account.
- 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

Check the following:

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, create it.
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-east1-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-east1-docker.pkg.dev/my-project/my-image:v1 is an invalid image path.

For more information, see Repository and image names.
Verify that the account that is pushing the image has permissions to write to the repository.
- The Cloud Build default service account has read and write permissions to repositories in the same Google Cloud project. If you are using a user-provided service account or pushing and pulling images across projects, grant the Artifact Registry Writer role to the service account that runs builds.
- By default Compute Engine, Cloud Run, and Google Kubernetes Engine have read permissions for repositories in the same project. If you are using a third-party tool in these environments to push images, you must grant the Artifact Registry Writer role to the runtime service account.
If Artifact Registry returned the message The repository has enabled tag immutability, 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 the troubleshooting steps in the GKE documentation.