{"record":{"id":"f9304ad06f20a882","repo":"testcontainers/testcontainers-java","slug":"container-startup-failed-for-image-dockerimagename","errorCode":null,"errorMessage":"Container startup failed for image ${dockerImageName}","messagePattern":"Container startup failed for image (.+?)","errorType":"exception","errorClass":"ContainerLaunchException","httpStatus":null,"severity":"critical","filePath":"core/src/main/java/org/testcontainers/containers/GenericContainer.java","lineNumber":346,"sourceCode":"            logger().debug(\"Starting container: {}\", getDockerImageName());\n\n            AtomicInteger attempt = new AtomicInteger(0);\n            Unreliables.retryUntilSuccess(\n                startupAttempts,\n                () -> {\n                    logger()\n                        .debug(\n                            \"Trying to start container: {} (attempt {}/{})\",\n                            getDockerImageName(),\n                            attempt.incrementAndGet(),\n                            startupAttempts\n                        );\n                    tryStart();\n                    return true;\n                }\n            );\n        } catch (Exception e) {\n            throw new ContainerLaunchException(\"Container startup failed for image \" + getDockerImageName(), e);\n        }\n    }\n\n    @UnstableAPI\n    @SneakyThrows\n    protected boolean canBeReused() {\n        for (Class<?> type = getClass(); type != GenericContainer.class; type = type.getSuperclass()) {\n            try {\n                Method method = type.getDeclaredMethod(\"containerIsCreated\", String.class);\n                if (method.getDeclaringClass() != GenericContainer.class) {\n                    logger().warn(\"{} can't be reused because it overrides {}\", getClass(), method.getName());\n                    return false;\n                }\n            } catch (NoSuchMethodException | NoClassDefFoundError e) {\n                // ignore\n            }\n        }\n","sourceCodeStart":328,"sourceCodeEnd":364,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/containers/GenericContainer.java#L328-L364","documentation":"GenericContainer.doStart wraps any exception raised while creating/starting the container in a ContainerLaunchException with this message, using the Docker image name for context. It is a wrapper: the root cause (nested exception) holds the actual failure — image pull failure, port conflict, startup check failure, wait strategy timeout, etc.","triggerScenarios":"Any failure inside container.start() → doStart(): image not found/unpullable, Ryuk or Docker unavailable, startup check failing (container never reaches running state), wait strategy timeout, reuse validation failing, or InspectContainerResponse problems during tryStart.","commonSituations":"Typo in image name/tag so the pull fails; Docker daemon not running; private registry requiring credentials; container crashes immediately so the wait strategy times out; insufficient resources (OOM) killing the container during startup.","solutions":["Read the 'Caused by' chain of this ContainerLaunchException to find the root cause.","Verify the image name/tag is correct and pullable (docker pull <image>).","Check the Docker daemon is up and reachable (docker info).","Increase the wait strategy timeout if the container starts slowly: container.waitingFor(Wait.forLogMessage(...)).withStartupTimeout(Duration.ofMinutes(2)).","Inspect container stdout/stderr logs printed by Testcontainers just before this exception for the real startup error."],"exampleFix":"// before\ntry {\n    container.start();\n} catch (ContainerLaunchException ignored) { }\n// after\ntry {\n    container.start();\n} catch (ContainerLaunchException e) {\n    // log the full cause chain to see the real startup failure\n    logger.error(\"Container startup failed\", e);\n    throw e;\n}","handlingStrategy":"try-catch","validationCode":"boolean dockerUp = java.util.Optional.ofNullable(\n    new ProcessBuilder(\"docker\", \"info\").start().waitFor() == 0).orElse(false);","typeGuard":"null","tryCatchPattern":"try {\n    container.start();\n} catch (ContainerLaunchException e) {\n    // root cause is in the cause chain — log it fully before retrying or failing\n    logger.error(\"Startup failed for {}\", container.getDockerImageName(), e);\n    throw e;\n}","preventionTips":["Check docker daemon health in CI before the test phase.","Pin image tags explicitly instead of :latest.","Pre-pull images in a CI setup step to catch auth/pull issues early.","Give wait strategies generous startup timeouts for heavy images."],"tags":["docker","container-startup","wrapper-exception"],"backgroundTag":"container-startup-failed","analyzedSha":"8e549514e3f01c57d70546fbb8599d138f3903e5","analyzedAt":"2026-09-12T14:56:41.227Z","contentChangedAt":"2026-09-12T14:56:41.227Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}