testcontainers/testcontainers-java · error · IllegalStateException

Container is started, but cannot be accessed by

Error message

Container is started, but cannot be accessed by (JDBC URL: %s), please check container logs

What it means

JdbcDatabaseContainer.waitUntilContainerStarted() repeatedly tries the container's test query until the startup timeout expires; if every attempt fails it throws this IllegalStateException including the JDBC URL and the last underlying connection exception as cause. It means the container process is running but the database never became reachable/ready.

Solutions

Inspect the container logs (container.getLogs()) for the database's startup error
Increase the startup timeout / use an appropriate wait strategy for the image
Verify username/password and JDBC URL parameters match the image's configuration
Check port mapping and that no other process conflicts

Example fix

// before
new PostgreSQLContainer("postgres:16"); // default timeout, flaky startup
// after
PostgreSQLContainer c = new PostgreSQLContainer("postgres:16");
c.withStartupTimeout(Duration.ofMinutes(3));
c.start();

Defensive patterns

Strategy: retry

Validate before calling

// before/at startup: ensure wait strategy passes and container.isRunning() is true
if (!container.isRunning()) throw new IllegalStateException("container exited early; check logs: " + container.getLogs());

Try / catch

try { connection = container.createConnection("?"); } catch (IllegalStateException e) { System.err.println(container.getLogs()); throw e; }

Prevention

Use withStartupTimeout(Duration) sized for slower CI machines
Inspect container logs on any startup failure
Confirm image credentials/env config match withUsername/withPassword

When it happens

Trigger: Startup timeout elapses while connect attempts keep failing during container startup wait.

Common situations: Database inside the container crashing at boot or taking longer than the timeout; wrong credentials so authentication fails every attempt; port mapping issues; test query incompatible with the DB image version.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

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

Appendix: source

Thrown at modules/jdbc/src/main/java/org/testcontainers/containers/JdbcDatabaseContainer.java:209

            } else {
                try (Connection connection = createConnection(""); Statement statement = connection.createStatement()) {
                    boolean testQuerySucceeded = statement.execute(this.getTestQueryString());
                    if (testQuerySucceeded) {
                        return;
                    }
                } catch (NoDriverFoundException e) {
                    // we explicitly want this exception to fail fast without retries
                    throw e;
                } catch (Exception e) {
                    lastConnectionException = e;
                    // ignore so that we can try again
                    logger().debug("Failure when trying test query", e);
                    Thread.sleep(100L);
                }
            }
        }

        throw new IllegalStateException(
            String.format(
                "Container is started, but cannot be accessed by (JDBC URL: %s), please check container logs",
                this.getJdbcUrl()
            ),
            lastConnectionException
        );
    }

    @Override
    protected void containerIsStarted(InspectContainerResponse containerInfo) {
        logger().info("Container is started (JDBC URL: {})", this.getJdbcUrl());
        runInitScriptIfRequired();
    }

    /**
     * Obtain an instance of the correct JDBC driver for this particular database container type
     *
     * @return a JDBC Driver

View on GitHub (pinned to 8e549514e3)