Troubleshooting Chainguard Containers on

Troubleshoot container and version availability

Wed, 02 Sep 2026 00:00:00 +0000

You need a container image, or a particular version of one, and you can’t pull it. The right next step depends on why it’s missing, and there are five distinct reasons. This guide helps you tell them apart and resolve each one.

First, distinguish between the public container registry and your organization’s registry:

The Chainguard Containers Directory at images.chainguard.dev is public. It lists every container image Chainguard builds, along with the tags, sizes, and metadata for each. Anyone can browse it.
Your organization’s registry at cgr.dev/$ORGANIZATION/ holds only the images your organization has access to. This is what your teams pull from.

Browsing an image in the Directory doesn’t mean your organization can pull it. For a fuller explanation of that distinction and how it relates to your subscription, see Onboard your teams.

Troubleshoot registry authentication errors

Wed, 09 Sep 2026 00:00:00 +0000

A login or pull against cgr.dev failed and you have an error string. This page maps the errors Chainguard’s registry returns to their causes and tells you what to check for each one.

If your pull fails for a container you can see in the Chainguard Containers Directory, the container most likely hasn’t been added to your organization yet. That case has its own guide: refer to Troubleshoot container and version availability.

Inspecting Chainguard Containers

Fri, 07 Jul 2023 15:21:01 +0000

Two questions come up repeatedly once you’re running Chainguard Containers: which exact build is this, and what software versions are inside it? A digest answers the first. The container’s SBOM answers the second.

The following examples pull from cgr.dev/chainguard/, the namespace that holds Chainguard’s Free containers, so they run as written. If you pull from your organization’s own registry, substitute cgr.dev/<organization>/.

Identify a build by its digest

A digest is a content-based hash of a container image. No two images share one, so pulling by digest returns the same image every time.

Debugging distroless container images

Thu, 18 May 2023 08:49:31 +0000

Because distroless images are minimal and don’t include a package manager or a shell, debugging issues that occur at runtime may require a distinctive approach.

In this article, we’ll discuss a few different strategies to debug distroless images.

1. Using development container image variants

Before moving a workload to a distroless runtime image, it is important to make sure that it runs without issues in a similar but less restrictive environment, which allows for easier debugging. It is also possible to make a temporary base image change from a distroless image to a fully featured image that offers more debugging capabilities.