Skip unreadable entries in image list

[Hokila]

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update

Motivation and Context

When one image entry has unreadable content, image list currently stops before rendering any entries. Resolve each image independently so readable images are still rendered, and log the skipped image reference and error to stderr so structured stdout remains valid.

Fixes #2149.

Testing

• Tested locally

• Added/updated tests

• Added/updated docs

• make test: 760 tests in 83 suites passed

• make check: formatting and license checks passed

[Hokila]

Hi @katiewasnothere, this PR is ready for review.

• make test: 760 tests in 83 suites passed
• make check: formatting and license checks passed
• The commit is GitHub SSH-signed and shows as Verified

Could you please approve the pending workflow and review this PR when you have a chance? Thank you!

[Hokila]

@egernst
I've rebased this PR onto the latest main. Could you please rerun the workflow?
The previous failure appears to have been caused by a runner timeout, so I believe it should pass on a rerun. Thanks!

[jglogan]

@Hokila Can you add a reproduction procedure to your description to show how you're triggering the error?

That will help us determine whether the changes we merged in apple/containerization#898 resolve this issue for the 1.3.1 release.

Once we know how things behave with those changes, let's look at this PR and see what would be the best UX for handling broken resources (images in this case).

[Hokila]

Thanks @jglogan. I’ll update the PR description with the exact reproduction procedure and retest it against a build that includes apple/containerization#898.

The current regression test covers per-image error isolation in the CLI, but it does not establish whether #898 already prevents or tolerates the underlying broken image-store state. I’ll document the before/after behavior once I’ve verified it with those changes.

After that, I’m happy to revisit whether the CLI-side skip-and-warn behavior is still needed and what the best UX should be for broken image resources.

[Hokila]

Thanks @jglogan. I reproduced the issue using the same image-store fixture across all three versions.

Reproduction setup

Environment:

• macOS 26, arm64
• One healthy image: docker.io/library/alpine:latest
• One broken image record: example.invalid/broken:latest
• The broken record contains a syntactically valid descriptor, but its root content blob is absent.

I used an isolated application root:

$ export APP_ROOT=/tmp/container-image-list-repro

$ container system start \
    --app-root "$APP_ROOT" \
    --disable-kernel-install

$ container image pull docker.io/library/alpine:latest

$ container system stop

I then added the following record to $APP_ROOT/state.json without creating its referenced content blob:

{
  "example.invalid/broken:latest": {
    "digest": "sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
    "size": 1,
    "mediaType": "application/vnd.oci.image.index.v1+json"
  }
}

The file below was intentionally absent:

$APP_ROOT/content/blobs/sha256/ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff

container 1.3.0, before containerization#898

Version:

$ container --version
container CLI version 1.3.0 (build: debug, commit: d96dfa3)

The default listing fails without rendering the healthy image:

$ container image list
Error: content with digest sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff

$ echo $?
1

JSON, YAML, and verbose output fail in the same way:

$ container image list --format json
Error: content with digest sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff

$ echo $?
1

$ container image list --format yaml
Error: content with digest sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff

$ echo $?
1

$ container image list --verbose
Error: content with digest sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff

$ echo $?
1

Quiet mode succeeds because it does not resolve the image content:

$ container image list -q
alpine:latest
example.invalid/broken:latest

$ echo $?
0

container 1.3.1, with containerization#898

Version:

$ container --version
container CLI version 1.3.1 (build: debug, commit: a9a62e2)

The same fixture still causes the complete listing to fail:

$ container image list
Error: content with digest sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff

$ echo $?
1

The other detailed formats also fail:

$ container image list --format json
Error: content with digest sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff

$ echo $?
1

$ container image list --format yaml
Error: content with digest sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff

$ echo $?
1

$ container image list --verbose
Error: content with digest sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff

$ echo $?
1

Quiet mode remains unaffected:

$ container image list -q
alpine:latest
example.invalid/broken:latest

$ echo $?
0

This indicates that apple/containerization#898 does not cover this particular case. The state record itself is readable and its descriptor digest is valid; the failure occurs later when the referenced root content blob cannot be found.

With this PR

Version:

$ container --version
container CLI version 1.3.0-3-gb7be756 (build: debug, commit: b7be756)

The broken image is reported, while the healthy image is still rendered:

$ container image list
skipping unreadable image: ["error": notFound: "content with digest sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff", "image": example.invalid/broken:latest]
NAME    TAG     DIGEST
alpine  latest  28bd5fe8b56d

$ echo $?
0

Verbose output also succeeds:

$ container image list --verbose
skipping unreadable image: ["error": notFound: "content with digest sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff", "image": example.invalid/broken:latest]
NAME    TAG     INDEX DIGEST  OS     ARCH     VARIANT  FULL SIZE  CREATED                         MANIFEST DIGEST
alpine  latest  28bd5fe8b56d  linux  amd64             3.8 MB     2026-06-16T00:01:29.967161902Z  79ff19e9084a
alpine  latest  28bd5fe8b56d  linux  arm      v6       3.6 MB     2026-06-16T00:00:25.329026823Z  bc301c70d7e7
alpine  latest  28bd5fe8b56d  linux  arm      v7       3.3 MB     2026-06-16T00:00:26.526765088Z  48bf253520b1
alpine  latest  28bd5fe8b56d  linux  arm64    v8       4.2 MB     2026-06-16T00:01:20.474100947Z  e7a1a92a5bfe
alpine  latest  28bd5fe8b56d  linux  386               3.7 MB     2026-06-16T00:01:19.360099979Z  6f5908cdf811
alpine  latest  28bd5fe8b56d  linux  ppc64le           3.8 MB     2026-06-16T00:00:15.017984356Z  a30366c2d264
alpine  latest  28bd5fe8b56d  linux  riscv64           3.6 MB     2026-06-16T05:59:15.56408535Z   20a26477b54f
alpine  latest  28bd5fe8b56d  linux  s390x             3.7 MB     2026-06-16T00:00:21.879382071Z  4eea4e45f63f

$ echo $?
0

I also captured JSON stdout and stderr separately:

$ container image list --format json > images.json 2> warning.log

$ echo $?
0

$ cat warning.log
skipping unreadable image: ["image": example.invalid/broken:latest, "error": notFound: "content with digest sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff"]

$ jq length images.json
1

$ jq -r '.[0].configuration.name' images.json
docker.io/library/alpine:latest

This confirms that:

1. The healthy image remains available in table, JSON, YAML, and verbose listings.
2. The broken image and underlying error are identified in a warning.
3. The warning is written to stderr and does not invalidate structured stdout.
4. The listing exits successfully.
5. containerization#898 does not independently resolve the missing-content case reproduced here.

The PR therefore fixes the listing behavior for this failure mode, although it does not repair or remove the underlying broken image resource.