{"record":{"id":"24f41b87faf68b58","repo":"testcontainers/testcontainers-java","slug":"could-not-create-start-container","errorCode":null,"errorMessage":"Could not create/start container","messagePattern":"Could not create/start container","errorType":"exception","errorClass":"ContainerLaunchException","httpStatus":null,"severity":"critical","filePath":"core/src/main/java/org/testcontainers/containers/GenericContainer.java","lineNumber":551,"sourceCode":"            }\n            if (e instanceof InvocationTargetException && e.getCause() instanceof Exception) {\n                e = (Exception) e.getCause();\n            }\n            logger().error(\"Could not start container\", e);\n\n            if (containerId != null) {\n                // Log output if startup failed, either due to a container failure or exception (including timeout)\n                final String containerLogs = getLogs();\n\n                if (containerLogs.length() > 0) {\n                    logger().error(\"Log output from the failed container:\\n{}\", containerLogs);\n                } else {\n                    logger().error(\"There are no stdout/stderr logs available for the failed container\");\n                }\n                stop();\n            }\n\n            throw new ContainerLaunchException(\"Could not create/start container\", e);\n        }\n    }\n\n    @VisibleForTesting\n    Checksum hashCopiedFiles() {\n        Checksum checksum = new Adler32();\n        Stream\n            .of(copyToFileContainerPathMap, copyToTransferableContainerPathMap)\n            .flatMap(it -> it.entrySet().stream())\n            .sorted(Entry.comparingByValue())\n            .forEach(entry -> {\n                byte[] pathBytes = entry.getValue().getBytes();\n                // Add path to the hash\n                checksum.update(pathBytes, 0, pathBytes.length);\n\n                entry.getKey().updateChecksum(checksum);\n            });\n        return checksum;","sourceCodeStart":533,"sourceCodeEnd":569,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/containers/GenericContainer.java#L533-L569","documentation":"This is the outermost wrapper in tryStart: after logging the container's stdout/stderr and calling stop() for cleanup, any exception from container creation/start (including all the IllegalStateExceptions above, and unknown failures) is rethrown as ContainerLaunchException('Could not create/start container'). The cause chain contains the precise reason.","triggerScenarios":"Any failure during container.start(): image pull errors, Docker daemon unreachable, create command rejection by the daemon (e.g. invalid host config, port conflicts), startup check or wait strategy failures, or errors in containerIsStarting hooks.","commonSituations":"Docker not installed/running on the dev machine or CI; port binding conflicts (address already in use); invalid withCreateContainerCmdModifier settings rejected by the daemon; network/rate limits failing the image pull.","solutions":["Always inspect the 'Caused by' chain of this exception — the root cause is there.","Verify Docker is running and reachable (docker info) and TESTCONTAINERS_* env/properties are sane.","Review the container logs printed immediately above the stack trace for the app-level failure.","Check for port conflicts and fix withCommand port or use withExposedPorts/withRandomPorts.","If the image pull fails, authenticate to the registry or verify the image reference."],"exampleFix":"// before\n} catch (Exception e) {\n    e.printStackTrace(); // loses the structured cause chain context\n}\n// after\n} catch (ContainerLaunchException e) {\n    Throwable root = e;\n    while (root.getCause() != null) root = root.getCause();\n    logger.error(\"Container failed to start, root cause: {}\", root.getMessage(), e);\n    throw e;\n}","handlingStrategy":"try-catch","validationCode":"// preflight before tests:\nProcess p = new ProcessBuilder(\"docker\", \"info\").start();\nboolean dockerReady = p.waitFor(10, java.util.concurrent.TimeUnit.SECONDS) && p.exitValue() == 0;","typeGuard":"null","tryCatchPattern":"try {\n    container.start();\n} catch (ContainerLaunchException e) {\n    // this is the outer wrapper — walk the cause chain to the root\n    Throwable t = e;\n    while (t.getCause() != null) t = t.getCause();\n    logger.error(\"Root cause: {}\", t.getMessage(), e);\n    throw e;\n}","preventionTips":["Run a docker-info preflight in CI before the test phase.","Pre-pull images and authenticate to private registries up front.","Avoid hard-coded host ports to prevent bind conflicts.","Read the cause chain — never diagnose from the wrapper message alone."],"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"}