testcontainers/testcontainers-java · error · SQLException

Could not load classpath init script

Error message

Could not load classpath init script: {}. Resource not found.

What it means

runInitScriptIfRequired throws this SQLException when the init script configured via TC_INITSCRIPT points to a classpath resource that cannot be found. Testcontainers logs a warning and fails the connection because the requested initialization SQL could not be located.

Solutions

1. Verify the file exists at the exact classpath path and is under src/test/resources (or src/main/resources)
2. Prefix the path with classpath: in TC_INITSCRIPT, e.g. TC_INITSCRIPT=classpath:sql/init.sql
3. Rebuild / run resource copying so the file lands in target/test-classes or build/resources/test
4. Check path casing and extension — classpath lookups are case-sensitive on Linux CI

Example fix

// before
String url = "jdbc:tc:postgresql:16:///mydb?TC_INITSCRIPT=init.sql";
// after
String url = "jdbc:tc:postgresql:16:///mydb?TC_INITSCRIPT=classpath:sql/init.sql"; // file at src/test/resources/sql/init.sql

String path = "sql/init.sql";
if (getClass().getClassLoader().getResource(path) == null)
    throw new IllegalStateException("Init script not on classpath: " + path);

try {
    runTestWithContainer();
} catch (SQLException e) {
    if (e.getMessage().contains("Resource not found")) {
        throw new IllegalStateException("Check TC_INITSCRIPT path and resources dir", e);
    }
    throw e;
}

When it happens

Trigger: jdbc:tc URL contains TC_INITSCRIPT=classpath:some/path/init.sql (or a plain path) but ClassLoader.getResource returns null — file not in src/test/resources, wrong path casing, or file not copied to the build output.

Common situations: init.sql placed in src/main/resources instead of src/test/resources; missing leading slash semantics confusion; build tool not copying resources; typo in the TC_INITSCRIPT path.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Could not load classpath init script
• Database name not supported
• Could not load classpath init script
• Error while executing init script
• Could not load classpath init script

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

Appendix: source

Thrown at modules/jdbc/src/main/java/org/testcontainers/jdbc/ContainerDatabaseDriver.java:219

     * @param databaseDelegate database delegate to apply init scripts to the database
     * @throws SQLException on script or DB error
     */
    private void runInitScriptIfRequired(final ConnectionUrl connectionUrl, DatabaseDelegate databaseDelegate)
        throws SQLException {
        if (connectionUrl.getInitScriptPath().isPresent()) {
            String initScriptPath = connectionUrl.getInitScriptPath().get();
            try {
                URL resource;
                if (initScriptPath.startsWith(FILE_PATH_PREFIX)) {
                    //relative workdir path
                    resource = new URL(initScriptPath);
                } else {
                    //classpath resource
                    resource = Thread.currentThread().getContextClassLoader().getResource(initScriptPath);
                }
                if (resource == null) {
                    LOGGER.warn("Could not load classpath init script: {}", initScriptPath);
                    throw new SQLException(
                        "Could not load classpath init script: " + initScriptPath + ". Resource not found."
                    );
                }

                String sql = IOUtils.toString(resource, StandardCharsets.UTF_8);
                ScriptUtils.executeDatabaseScript(databaseDelegate, initScriptPath, sql);
            } catch (IOException e) {
                LOGGER.warn("Could not load classpath init script: {}", initScriptPath);
                throw new SQLException("Could not load classpath init script: " + initScriptPath, e);
            } catch (ScriptException e) {
                LOGGER.error("Error while executing init script: {}", initScriptPath, e);
                throw new SQLException("Error while executing init script: " + initScriptPath, e);
            }
        }
    }

    /**
     * Run an init function (must be a public static method on an accessible class).

View on GitHub (pinned to 8e549514e3)