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

### Project ID syntax in the Docker CLI

Because of how Docker treats colons, when you use the Docker CLI, you must
replace colons (`:`) in your project ID with a forward slash (`/`).

For more information, see [Domain-scoped projects](https://docs.cloud.google.com/artifact-registry/docs/docker/names#domain).


### 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](https://docs.cloud.google.com/artifact-registry/docs/docker/names).
2. Verify that the account that is pulling the image has the correct [permissions](https://docs.cloud.google.com/artifact-registry/docs/access-control) to read from the repository. If you have [disabled automatic role granting to service accounts](https://docs.cloud.google.com/resource-manager/docs/organization-policy/restricting-service-accounts#disable_service_account_default_grants), 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](https://docs.cloud.google.com/artifact-registry/docs/access-control#grant) to the account that interacts with the repository.
     - Configure the client to authenticate to the repository.
       - [Docker authentication](https://docs.cloud.google.com/artifact-registry/docs/docker/authentication) instructions
       - [Troubleshooting containerd node images on Google Kubernetes Engine](https://docs.cloud.google.com/artifact-registry/docs/integrate-gke#troubleshooting_containerd_node_images)

### 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](https://docs.cloud.google.com/artifact-registry/docs/repositories/create-repos) 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](https://docs.cloud.google.com/artifact-registry/docs/docker/names).
3. Verify that the account that is pushing the image has [permissions](https://docs.cloud.google.com/artifact-registry/docs/access-control) to write to the repository. If you have [disabled automatic role granting to service accounts](https://docs.cloud.google.com/resource-manager/docs/organization-policy/restricting-service-accounts#disable_service_account_default_grants), 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](https://docs.cloud.google.com/artifact-registry/docs/integrate-gke#permissions) to pull from Artifact Registry.
- Review [Troubleshoot image pulls](https://docs.cloud.google.com/kubernetes-engine/docs/troubleshooting/image-pulls) in the GKE documentation.