{"record":{"id":"17749d7c889aed62","repo":"testcontainers/testcontainers-java","slug":"an-exception-while-executing-the-internal-check","errorCode":null,"errorMessage":"An exception while executing the internal check: {}","messagePattern":"An exception while executing the internal check: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"core/src/main/java/org/testcontainers/containers/wait/internal/InternalCommandPortListeningCheck.java","lineNumber":58,"sourceCode":"        Instant before = Instant.now();\n        try {\n            ExecResult result = ExecInContainerPattern.execInContainer(\n                waitStrategyTarget.getDockerClient(),\n                waitStrategyTarget.getContainerInfo(),\n                \"/bin/sh\",\n                \"-c\",\n                command.toString()\n            );\n            log.trace(\n                \"Check for {} took {}. Result code '{}', stdout message: '{}'\",\n                internalPorts,\n                Duration.between(before, Instant.now()),\n                result.getExitCode(),\n                result.getStdout()\n            );\n            int exitCode = result.getExitCode();\n            if (exitCode != 0 && exitCode != 1) {\n                log.warn(\"An exception while executing the internal check: {}\", result);\n            }\n            return exitCode == 0;\n        } catch (Exception e) {\n            throw new IllegalStateException(e);\n        }\n    }\n}\n","sourceCodeStart":40,"sourceCodeEnd":66,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/containers/wait/internal/InternalCommandPortListeningCheck.java#L40-L66","documentation":"InternalCommandPortListeningCheck.call() runs an internal shell command inside the container to check whether ports are listening. If the command's exit code is neither 0 nor 1 (i.e. an unexpected failure such as the command being missing or the container erroring), the raw ExecutableResult is logged with this warning. The check then returns false, which the surrounding wait strategy treats as 'ports not yet listening' until timeout.","triggerScenarios":"Executing the internal port-listening check via wait strategies that use InternalCommandPortListeningCheck (e.g. PortListeningCheck / WaitAllStrategy usage) when the in-container command exits with an unexpected code (not 0 or 1), or throws, causing the wrapped IllegalStateException.","commonSituations":"Containers lacking a shell or /proc/net access (distroless, alpine without sh), containers that stopped during the wait, or images whose shell blocks the check command; users then see the wait strategy time out with this warning beforehand.","solutions":["Inspect the logged result's exit code/stdout to find why the in-container check command failed.","Use a base image with a POSIX shell (/bin/sh) and /proc available so the internal check can execute.","Or switch to ExternalPortListeningCheck-style behavior by ensuring the ports are mapped to the host and used by the wait strategy.","Increase wait timeout only after confirming the container itself stays healthy."],"exampleFix":"// before\nnew GenericContainer<>(\"myorg/distroless-app\")\n    .waitingFor(Wait.forListeningPort()); // internal check fails inside distroless\n// after\nnew GenericContainer<>(\"myorg/app-with-shell\")\n    .waitingFor(Wait.forHttp(\"/health\").forStatusCode(200));","handlingStrategy":"try-catch","validationCode":"// Prefer images with a POSIX shell; verify before waiting:\nContainer.ExecResult r = container.execInContainer(\"sh\", \"-c\", \"command -v sh\");\nif (r.getExitCode() != 0) { /* choose non-internal wait strategy */ }","typeGuard":null,"tryCatchPattern":"try {\n    container.waitingFor(Wait.forListeningPort()).start();\n} catch (ContainerLaunchException | IllegalStateException e) {\n    // inspect InternalCommandPortListeningCheck warning for exit code/stdout\n}","preventionTips":["Use base images with /bin/sh and /proc mounted.","Prefer Wait.forHttp or host-side checks for distroless images.","Keep containers alive during waits (no early exits)."],"tags":["wait-strategy","port-check","container","health-check"],"backgroundTag":"unexpected-response-shape","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"}