testcontainers/testcontainers-java · error · UncategorizedScriptException

Error while executing init script

Error message

Error while executing init script: ${initScriptPath}

What it means

ScriptUtils.runInitScript caught a ScriptException thrown while executing the init script and rethrows it as UncategorizedScriptException with this message. This means the script loaded fine but failed during execution against the database (e.g. SQL error inside executeDatabaseScript).

Solutions

  1. Inspect the nested UncategorizedScriptException cause for the actual SQL error and line number.
  2. Fix the SQL in the init script (syntax, dialect compatibility, ordering).
  3. Make scripts idempotent (CREATE TABLE IF NOT EXISTS) when containers are reused across tests.
  4. Test the script directly against the target database version.

Example fix

// before (init.sql)
CREATE TABLE users (id INT PRIMARY KEY); // rerun -> already exists
// after (init.sql)
CREATE TABLE IF NOT EXISTS users (id INT PRIMARY KEY);
Defensive patterns

Strategy: try-catch

Try / catch

try {
    ScriptUtils.runInitScript(delegate, initScriptPath);
} catch (UncategorizedScriptException e) {
    if (e.getMessage().startsWith("Error while executing init script")) {
        Throwable sql = e.getCause(); // real SQL failure with details
        LOG.error("Init script failed: {}", sql.getMessage());
    }
    throw e;
}

Prevention

When it happens

Trigger: executeDatabaseScript throwing ScriptException due to SQL syntax errors, duplicate table creation, constraint violations, or connection failures while running initScriptPath statements.

Common situations: Scripts written for one database dialect run against another; re-running non-idempotent DDL on a reused container; referencing tables/columns that don't exist yet.

Understand the failure class

Background: "query failed", "%w: SQL error" — wrapped database query errors in Go libraries explained — this error's family across 3 libraries.

Related errors

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

Appendix: source

Thrown at modules/database-commons/src/main/java/org/testcontainers/ext/ScriptUtils.java:219

        try {
            URL resource = Thread.currentThread().getContextClassLoader().getResource(initScriptPath);
            if (resource == null) {
                resource = ScriptUtils.class.getClassLoader().getResource(initScriptPath);
                if (resource == null) {
                    LOGGER.warn("Could not load classpath init script: {}", initScriptPath);
                    throw new ScriptLoadException(
                        "Could not load classpath init script: " + initScriptPath + ". Resource not found."
                    );
                }
            }
            String scripts = IOUtils.toString(resource, StandardCharsets.UTF_8);
            executeDatabaseScript(databaseDelegate, initScriptPath, scripts);
        } catch (IOException e) {
            LOGGER.warn("Could not load classpath init script: {}", initScriptPath);
            throw new ScriptLoadException("Could not load classpath init script: " + initScriptPath, e);
        } catch (ScriptException e) {
            LOGGER.error("Error while executing init script: {}", initScriptPath, e);
            throw new UncategorizedScriptException("Error while executing init script: " + initScriptPath, e);
        }
    }

    public static void executeDatabaseScript(DatabaseDelegate databaseDelegate, String scriptPath, String script)
        throws ScriptException {
        executeDatabaseScript(
            databaseDelegate,
            scriptPath,
            script,
            false,
            false,
            DEFAULT_COMMENT_PREFIX,
            DEFAULT_STATEMENT_SEPARATOR,
            DEFAULT_BLOCK_COMMENT_START_DELIMITER,
            DEFAULT_BLOCK_COMMENT_END_DELIMITER
        );
    }

View on GitHub (pinned to 8e549514e3)