testcontainers/testcontainers-java · warning

The architecture ' ' for image ' ' (ID ) does not match the…

Error message

The architecture '{}' for image '{}' (ID {}) does not match the Docker server architecture '{}'. This will cause the container to execute much more slowly due to emulation and may lead to timeout failures.

What it means

During tryStart, checkForEmulation() compares the pulled image's architecture with the Docker server architecture. On mismatch the container runs under emulation (e.g. qemu via binfmt), which is much slower and can cause startup timeouts; the returned warning text is logged at WARN. Startup still proceeds.

Solutions

1. Use an image tag with a multi-arch manifest (or an arch-specific tag matching the host)
2. Configure Docker Desktop / buildx with correct platform support (binfmt/qemu installed)
3. Switch to a different base image that supports your architecture
4. Increase startup timeout if emulation is acceptable but slow

Example fix

// before
new GenericContainer<>("someimage:1.0") // x86-only tag on arm64 host
// after
new GenericContainer<>(DockerImageName.parse("someimage:2.0")) // multi-arch tag

// Compare image arch with server arch before starting
String serverArch = dockerClient.versionCmd().exec().getArch();
InspectImageResponse img = dockerClient.inspectImageCmd("someimage:1.0").exec();
String imageArch = img.getArch();
if (!imageArch.equals(serverArch)) {
    log.warn("Arch mismatch {} vs {} — pick a multi-arch tag", imageArch, serverArch);
}

When it happens

Trigger: Starting an image whose platform arch (e.g. arm64) differs from the Docker daemon arch (e.g. amd64) — typically by using an image tag without a matching multi-arch manifest or forcing a platform.

Common situations: Developing on Apple Silicon (M1/M2) with x86-only images; CI runners of a different architecture than developers' machines; pinning old tags lacking arm64 variants.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• A large amount of data was sent to the Docker daemon
• An error occurred
• An error occurred
• Can not connect to Ryuk at
• Can't close DockerClient

AI-assisted analysis of testcontainers/testcontainers-java@8e549514e3 (2026-09-12). Data as JSON: /api/errors/9912f437d1825a24. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/org/testcontainers/containers/GenericContainer.java:472

                        () -> dockerClient.inspectContainerCmd(containerId).exec(),
                        inspectContainerResponse -> {
                            Set<ExposedPort> exposedAndMappedPorts = inspectContainerResponse
                                .getNetworkSettings()
                                .getPorts()
                                .getBindings()
                                .entrySet()
                                .stream()
                                .filter(it -> Objects.nonNull(it.getValue())) // filter out exposed but not yet mapped
                                .map(Entry::getKey)
                                .collect(Collectors.toSet());

                            return exposedAndMappedPorts.containsAll(this.containerDef.getExposedPorts());
                        }
                    );

            String emulationWarning = checkForEmulation();
            if (emulationWarning != null) {
                logger().warn(emulationWarning);
            }

            // Tell subclasses that we're starting
            containerIsStarting(containerInfo, reused);

            // Wait until the container has reached the desired running state
            if (!this.startupCheckStrategy.waitUntilStartupSuccessful(this)) {
                // Bail out, don't wait for the port to start listening.
                // (Exception thrown here will be caught below and wrapped)
                throw new IllegalStateException("Container did not start correctly.");
            }

            // Wait until the process within the container has become ready for use (e.g. listening on network, log message emitted, etc).
            try {
                waitUntilContainerStarted();
            } catch (Exception e) {
                logger().debug("Wait strategy threw an exception", e);
                InspectContainerResponse inspectContainerResponse = null;

View on GitHub (pinned to 8e549514e3)