{"record":{"id":"9912f437d1825a24","repo":"testcontainers/testcontainers-java","slug":"the-architecture-for-image-id-does-not-match-the-docker","errorCode":null,"errorMessage":"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.","messagePattern":"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\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"core/src/main/java/org/testcontainers/containers/GenericContainer.java","lineNumber":472,"sourceCode":"                        () -> dockerClient.inspectContainerCmd(containerId).exec(),\n                        inspectContainerResponse -> {\n                            Set<ExposedPort> exposedAndMappedPorts = inspectContainerResponse\n                                .getNetworkSettings()\n                                .getPorts()\n                                .getBindings()\n                                .entrySet()\n                                .stream()\n                                .filter(it -> Objects.nonNull(it.getValue())) // filter out exposed but not yet mapped\n                                .map(Entry::getKey)\n                                .collect(Collectors.toSet());\n\n                            return exposedAndMappedPorts.containsAll(this.containerDef.getExposedPorts());\n                        }\n                    );\n\n            String emulationWarning = checkForEmulation();\n            if (emulationWarning != null) {\n                logger().warn(emulationWarning);\n            }\n\n            // Tell subclasses that we're starting\n            containerIsStarting(containerInfo, reused);\n\n            // Wait until the container has reached the desired running state\n            if (!this.startupCheckStrategy.waitUntilStartupSuccessful(this)) {\n                // Bail out, don't wait for the port to start listening.\n                // (Exception thrown here will be caught below and wrapped)\n                throw new IllegalStateException(\"Container did not start correctly.\");\n            }\n\n            // Wait until the process within the container has become ready for use (e.g. listening on network, log message emitted, etc).\n            try {\n                waitUntilContainerStarted();\n            } catch (Exception e) {\n                logger().debug(\"Wait strategy threw an exception\", e);\n                InspectContainerResponse inspectContainerResponse = null;","sourceCodeStart":454,"sourceCodeEnd":490,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/containers/GenericContainer.java#L454-L490","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use an image tag with a multi-arch manifest (or an arch-specific tag matching the host)","Configure Docker Desktop / buildx with correct platform support (binfmt/qemu installed)","Switch to a different base image that supports your architecture","Increase startup timeout if emulation is acceptable but slow"],"exampleFix":"// before\nnew GenericContainer<>(\"someimage:1.0\") // x86-only tag on arm64 host\n// after\nnew GenericContainer<>(DockerImageName.parse(\"someimage:2.0\")) // multi-arch tag","handlingStrategy":"validation","validationCode":"// Compare image arch with server arch before starting\nString serverArch = dockerClient.versionCmd().exec().getArch();\nInspectImageResponse img = dockerClient.inspectImageCmd(\"someimage:1.0\").exec();\nString imageArch = img.getArch();\nif (!imageArch.equals(serverArch)) {\n    log.warn(\"Arch mismatch {} vs {} — pick a multi-arch tag\", imageArch, serverArch);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Prefer multi-arch image tags","Pin arch-specific tags when multi-arch is unavailable","On Apple Silicon, verify images support arm64 or have working emulation","Increase startup timeouts when emulation is unavoidable"],"tags":["architecture","emulation","docker","performance"],"backgroundTag":"architecture-mismatch","analyzedSha":"8e549514e3f01c57d70546fbb8599d138f3903e5","analyzedAt":"2026-09-12T14:56:41.227Z","contentChangedAt":"2026-09-12T14:56:41.227Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}