testcontainers/testcontainers-java · error · IllegalStateException

Authentication failed.

Error message

Authentication failed.

What it means

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.

Solutions

1. Restart Docker and clean up stale containers (`docker rm -f $(docker ps -aq)` for testcontainers leftovers).
2. Retry the test — often transient during container startup.
3. Check for port conflicts on the port the SSH proxy uses.
4. Update Testcontainers; older versions had SSH setup races.

// ensure a clean state first: `docker ps -q --filter label=org.testcontainers=true` should not list stale containers

try { container.start(); } catch (IllegalStateException e) { if ("Authentication failed.".equals(e.getMessage())) { dockerCleanup(); retryStart(); } throw e; }

When it happens

Trigger: 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).

Common situations: 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.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• Could not obtain SSH_CONNECTION environment variable for…
• Unexpected pattern for SSH_CONNECTION for docker machine -…
• Your provided admin password is too short and will not work…

AI-assisted analysis of testcontainers/testcontainers-java@8e549514e3 (2026-09-12). Data as JSON: /api/errors/b3f9c2938feeefea. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/org/testcontainers/containers/PortForwardingContainer.java:55

    @Getter(value = AccessLevel.PRIVATE, lazy = true)
    private final Connection sshConnection = createSSHSession();

    @SneakyThrows
    private Connection createSSHSession() {
        container = new GenericContainer<>(DEFINITION);
        container.start();

        Connection connection = new Connection(container.getHost(), container.getMappedPort(22));

        connection.setTCPNoDelay(true);
        connection.connect(
            (hostname, port, serverHostKeyAlgorithm, serverHostKey) -> true,
            (int) Duration.ofSeconds(30).toMillis(),
            (int) Duration.ofSeconds(30).toMillis()
        );

        if (!connection.authenticateWithPassword("root", PASSWORD)) {
            throw new IllegalStateException("Authentication failed.");
        }

        return connection;
    }

    @SneakyThrows
    public void exposeHostPort(int port) {
        exposeHostPort(port, port);
    }

    @SneakyThrows
    public void exposeHostPort(int hostPort, int containerPort) {
        if (exposedPorts.add(new AbstractMap.SimpleEntry<>(hostPort, containerPort))) {
            getSshConnection().requestRemotePortForwarding("", containerPort, "localhost", hostPort);
        }
    }

    void start() {

View on GitHub (pinned to 8e549514e3)