testcontainers/testcontainers-java · error · SQLException

Could not load classpath init script

Error message

Could not load classpath init script: {}

What it means

If reading the init script resource throws an IOException, runInitScriptIfRequired wraps it in this SQLException. The resource was found but its content could not be read (I/O error while loading it).

Solutions

1. Check file permissions and that the resource is readable by the test process user
2. Re-copy/rebuild the resource in the build output; verify integrity
3. If loading from a jar, ensure the jar is complete and not corrupted
4. As an alternative, pass the script inline with TC_INITSQL or use withInitScript on the container

Example fix

// before
String url = "jdbc:tc:postgresql:16:///mydb?TC_INITSCRIPT=file:/mnt/share/init.sql";
// after
String url = "jdbc:tc:postgresql:16:///mydb?TC_INITSCRIPT=classpath:sql/init.sql"; // local, packaged resource

URL r = getClass().getClassLoader().getResource(initPath);
if (r == null) throw new IllegalStateException("Missing resource: " + initPath);
try (InputStream in = r.openStream()) { in.readAllBytes(); } // readable check

try {
    runTestWithContainer();
} catch (SQLException e) {
    if (e.getCause() instanceof IOException) {
        throw new IllegalStateException("Init script unreadable: " + e.getMessage(), e);
    }
    throw e;
}

When it happens

Trigger: TC_INITSCRIPT resource resolves but IOUtils.toString fails reading it — corrupted resource, unreadable file, closed stream, or an IOException while reading from the resolved URL.

Common situations: File permission issues on CI; network-mounted resources failing mid-read; unusual classloader (fat jar / shaded) that can open but not stream the resource.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• Could not load classpath init script
• Could not load classpath init script
• Error while executing init script
• Could not load classpath init script
• Error while executing init script

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

Appendix: source

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

                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).
     *
     * @param connectionUrl {@link ConnectionUrl} instance representing JDBC Url with r init function declarations.
     * @param connection    JDBC connection to apply init functions to.
     * @throws SQLException on script or DB error
     */
    private void runInitFunctionIfRequired(final ConnectionUrl connectionUrl, Connection connection)
        throws SQLException {
        if (connectionUrl.getInitFunction().isPresent()) {
            String className = connectionUrl.getInitFunction().get().getClassName();

View on GitHub (pinned to 8e549514e3)