{"record":{"id":"b3f9c2938feeefea","repo":"testcontainers/testcontainers-java","slug":"authentication-failed","errorCode":null,"errorMessage":"Authentication failed.","messagePattern":"Authentication failed\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/testcontainers/containers/PortForwardingContainer.java","lineNumber":55,"sourceCode":"    @Getter(value = AccessLevel.PRIVATE, lazy = true)\n    private final Connection sshConnection = createSSHSession();\n\n    @SneakyThrows\n    private Connection createSSHSession() {\n        container = new GenericContainer<>(DEFINITION);\n        container.start();\n\n        Connection connection = new Connection(container.getHost(), container.getMappedPort(22));\n\n        connection.setTCPNoDelay(true);\n        connection.connect(\n            (hostname, port, serverHostKeyAlgorithm, serverHostKey) -> true,\n            (int) Duration.ofSeconds(30).toMillis(),\n            (int) Duration.ofSeconds(30).toMillis()\n        );\n\n        if (!connection.authenticateWithPassword(\"root\", PASSWORD)) {\n            throw new IllegalStateException(\"Authentication failed.\");\n        }\n\n        return connection;\n    }\n\n    @SneakyThrows\n    public void exposeHostPort(int port) {\n        exposeHostPort(port, port);\n    }\n\n    @SneakyThrows\n    public void exposeHostPort(int hostPort, int containerPort) {\n        if (exposedPorts.add(new AbstractMap.SimpleEntry<>(hostPort, containerPort))) {\n            getSshConnection().requestRemotePortForwarding(\"\", containerPort, \"localhost\", hostPort);\n        }\n    }\n\n    void start() {","sourceCodeStart":37,"sourceCodeEnd":73,"githubUrl":"https://github.com/testcontainers/testcontainers-java/blob/8e549514e3f01c57d70546fbb8599d138f3903e5/core/src/main/java/org/testcontainers/containers/PortForwardingContainer.java#L37-L73","documentation":"PortForwardingContainer sets up an SSH connection (trilead-ssh2) to the docker-credential-proxy sidecar and authenticates as root with a fixed internal password. If authenticateWithPassword returns false, the library throws IllegalStateException(\"Authentication failed.\") — this indicates the SSH server inside the managed container rejected the credentials, usually a transient startup failure or a broken Docker environment.","triggerScenarios":"createSSHSession() calls connection.authenticateWithPassword(\"root\", PASSWORD) and it returns false — the internal SSH container is not ready, was started with different credentials, or the connection actually landed on a different SSH server (port collision).","commonSituations":"Docker daemon under heavy load so the sidecar is not fully initialized, stale containers from a previous crashed run, another service bound to the same port, corporate security software interfering.","solutions":["Restart Docker and clean up stale containers (`docker rm -f $(docker ps -aq)` for testcontainers leftovers).","Retry the test — often transient during container startup.","Check for port conflicts on the port the SSH proxy uses.","Update Testcontainers; older versions had SSH setup races."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// ensure a clean state first: `docker ps -q --filter label=org.testcontainers=true` should not list stale containers","typeGuard":null,"tryCatchPattern":"try { container.start(); } catch (IllegalStateException e) { if (\"Authentication failed.\".equals(e.getMessage())) { dockerCleanup(); retryStart(); } throw e; }","preventionTips":["Clean stale testcontainers containers after aborted CI runs.","Keep Docker Engine and Testcontainers versions current.","Avoid port-colliding services on the same Docker host."],"tags":["ssh","authentication","port-forwarding"],"backgroundTag":"authentication-required","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"}