testcontainers/testcontainers-java · error · org.testcontainers.ext.UncategorizedScriptException

Failed to execute database script from resource [" + script…

Error message

Failed to execute database script from resource [" + script + "]

What it means

ScriptUtils.executeDatabaseScript catches any non-ScriptException thrown while executing a database script and wraps it in UncategorizedScriptException with this message naming the script resource. It's the general-purpose wrapper for unexpected failures (connection errors, runtime exceptions from the delegate) during script execution.

Solutions

  1. Look at the cause inside UncategorizedScriptException for the root failure.
  2. Ensure the database container is started and its wait strategy satisfied before executing scripts.
  3. Verify the DatabaseDelegate/connection settings (url, username, password).
  4. If the failure is a genuine script error, expect a plain ScriptException instead; refactor so script errors aren't masked.

Example fix

// before
ScriptUtils.executeDatabaseScript(delegate, "init.sql", script); // db not ready
// after
Awaitility.await().until(container::isRunning);
ScriptUtils.executeDatabaseScript(delegate, "init.sql", script);
Defensive patterns

Strategy: try-catch

Validate before calling

if (!container.isRunning()) {
    throw new IllegalStateException("Database container must be running before executing scripts");
}

Try / catch

try {
    ScriptUtils.executeDatabaseScript(delegate, scriptPath, script);
} catch (UncategorizedScriptException e) {
    if (e.getMessage().startsWith("Failed to execute database script from resource")) {
        Throwable root = e.getCause(); // connection/runtime failure details
    }
    throw e;
}

Prevention

When it happens

Trigger: Any exception other than ScriptException escaping the statement execution loop: DatabaseDelegate connection failures, RuntimeExceptions from JDBC, null/blank statements handling bugs.

Common situations: Database not yet ready when the script runs; wrong credentials for the delegate; a driver throwing a runtime exception mid-script.

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/be7c907279859f83. Report an issue: GitHub.

Appendix: source

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

                blockCommentStartDelimiter,
                blockCommentEndDelimiter,
                statements
            );

            try (DatabaseDelegate closeableDelegate = databaseDelegate) {
                closeableDelegate.execute(statements, scriptPath, continueOnError, ignoreFailedDrops);
            }

            long elapsedTime = TimeUnit.NANOSECONDS.toMillis(System.nanoTime() - startTime);
            if (LOGGER.isInfoEnabled()) {
                LOGGER.info("Executed database script from " + scriptPath + " in " + elapsedTime + " ms.");
            }
        } catch (Exception ex) {
            if (ex instanceof ScriptException) {
                throw (ScriptException) ex;
            }

            throw new UncategorizedScriptException(
                "Failed to execute database script from resource [" + script + "]",
                ex
            );
        }
    }

    public static class ScriptLoadException extends RuntimeException {

        public ScriptLoadException(String message) {
            super(message);
        }

        public ScriptLoadException(String message, Throwable cause) {
            super(message, cause);
        }
    }

    public static class ScriptParseException extends RuntimeException {

View on GitHub (pinned to 8e549514e3)