Testcontainers "no matching manifest" (ARM vs amd64) in CI

By Daniel Zoghalchali·Latchkey

The image you asked for is not published for the runner CPU architecture. An amd64-only image on an ARM runner (or the reverse) has no matching manifest, so the pull fails before any container starts.

What this error means

Setup fails while pulling with "no matching manifest for linux/arm64/v8 in the manifest list entries" (or linux/amd64), usually after switching runner architecture.

Testcontainers

Could not pull image: no matching manifest for linux/arm64/v8 in the manifest list entries

Common causes

The image has no build for the runner architecture

A single-arch image cannot run on a runner of a different CPU architecture, so its manifest list has no matching entry.

A new ARM runner pulling amd64-only images

Moving tests to ARM runners exposes images that were only ever built for amd64.

How to fix it

Use a multi-arch image or pin the platform

Prefer images that publish both amd64 and arm64, or pin the platform Testcontainers requests to one the image supports.

Java

new GenericContainer<>(DockerImageName.parse("postgres:16"))
    // ensure the image tag has a manifest for the runner arch

Run tests on the architecture the image supports

If an image is amd64-only, run that job on an amd64 runner rather than ARM.

.github/workflows/ci.yml

jobs:
  test:
    runs-on: ubuntu-latest   # amd64

How to prevent it

Prefer multi-arch images for cross-architecture CI.
Match the runner architecture to what your test images publish.
Audit single-arch dependencies before adopting ARM runners.

Frequently asked questions

What causes ""no matching manifest for linux/...""?