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

Error while executing init script

Error message

Error while executing init script: ${initScriptPath}

What it means

After Cassandra starts and the init script is loaded, runInitScriptIfRequired executes its statements via CassandraDatabaseDelegate. If a CQL statement in the script fails (ScriptUtils.ScriptStatementFailedException), the container wraps it in an UncategorizedScriptException with this message. Unlike error 76 the script was found — a statement inside it is invalid or failed at runtime.

Solutions

  1. Read the accompanying log/exception for the exact failing statement and Cassandra's error message
  2. Validate the script by running it manually against the same Cassandra version (docker run + cqlsh)
  3. Fix the offending CQL (syntax, ordering, existence checks like CREATE TABLE IF NOT EXISTS)
  4. Align the script with the container's Cassandra version if it uses version-specific syntax

Example fix

// before (init.cql)
CREATE TABLE users (id uuid PRIMARY KEY, name text);
CREATE TABLE users (id uuid PRIMARY KEY, name text); -- duplicate -> fails
// after
CREATE TABLE IF NOT EXISTS users (id uuid PRIMARY KEY, name text);
Defensive patterns

Strategy: try-catch

Validate before calling

// pre-validate the script offline with an embedded validator or run against a scratch Cassandra container before the test suite

Try / catch

try {
    container.start();
} catch (UncategorizedScriptException e) {
    Throwable root = getRootCause(e);
    log.error("CQL in {} failed: {}", container.getInitScript(), root.getMessage());
    throw new AssertionError("Fix init script statement: " + container.getInitScript(), e);
}

Prevention

When it happens

Trigger: withInitScript(...) pointing to a loadable script whose CQL contains syntax errors, references a non-existent keyspace/table, violates constraints (duplicate CREATE, invalid type), or fails because the server rejected the statement.

Common situations: Scripts written for a different Cassandra version (unsupported syntax); statements depending on objects created earlier in the same script that failed silently or in wrong order; invalid CQL copied from cqlsh with cqlsh-only directives.

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

Appendix: source

Thrown at modules/cassandra/src/main/java/org/testcontainers/cassandra/CassandraContainer.java:111

    private void runInitScriptIfRequired() {
        if (this.initScriptPath != null) {
            try {
                final MountableFile originalInitScript = MountableFile.forClasspathResource(this.initScriptPath);
                // The init script is executed as is by the cqlsh command, so copy it into the container. The name
                // of the script is generic since it's not important to keep the original name.
                copyFileToContainer(originalInitScript, DEFAULT_INIT_SCRIPT_FILENAME);
                new CassandraDatabaseDelegate(this).execute(null, DEFAULT_INIT_SCRIPT_FILENAME, -1, false, false);
            } catch (IllegalArgumentException e) {
                // MountableFile.forClasspathResource will throw an IllegalArgumentException if the resource cannot
                // be found.
                logger().warn("Could not load classpath init script: {}", this.initScriptPath);
                throw new ScriptLoadException(
                    "Could not load classpath init script: " + this.initScriptPath + ". Resource not found.",
                    e
                );
            } catch (ScriptUtils.ScriptStatementFailedException e) {
                logger().error("Error while executing init script: {}", this.initScriptPath, e);
                throw new ScriptUtils.UncategorizedScriptException(
                    "Error while executing init script: " + this.initScriptPath,
                    e
                );
            }
        }
    }

    /**
     * Initialize Cassandra with the custom overridden Cassandra configuration
     * <p>
     * Be aware, that Docker effectively replaces all /etc/cassandra content with the content of config location, so if
     * Cassandra.yaml in configLocation is absent or corrupted, then Cassandra just won't launch.
     *
     * @param configLocation relative classpath with the directory that contains cassandra.yaml and other configuration
     *                       files
     * @return The updated {@link CassandraContainer}.
     */
    public CassandraContainer withConfigurationOverride(String configLocation) {

View on GitHub (pinned to 8e549514e3)