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

Script execution failed

Error message

Script execution failed (%s:%d): %s

What it means

CassandraDatabaseDelegate.execute runs a CQL statement/script inside the Cassandra container via ExecConfig and inspects the result. When the executed command reports a non-zero/failed outcome with stderr output (and error logs are not silenced), it throws ScriptStatementFailedException formatted as 'Script execution failed (%s:%d): %s' with the statement, line number, and script path.

Solutions

  1. Inspect the logged stderr ('CQL script execution failed with error') for the server-side reason
  2. Fix the CQL statement; validate it manually via cqlsh in the same container version
  3. If thrown during startup, wait for full readiness before executing CQL (use follow-up wait strategies / execute after containerIsStarted)
  4. Retry schema statements if caused by transient schema agreement delays, or set a larger schema agreement timeout in Cassandra config

Example fix

// before
container.executeCql("ALTER TABLE keyspace.t ADD col int;"); // t does not exist yet
// after
container.executeCql("CREATE TABLE IF NOT EXISTS keyspace.t (id uuid PRIMARY KEY, col int);");
container.executeCql("ALTER TABLE keyspace.t ADD col int;");
Defensive patterns

Strategy: try-catch

Validate before calling

// sanity-check CQL with a lightweight parser or dry-run against a scratch container before executing in tests

Try / catch

try {
    container.executeCql(statement);
} catch (ScriptStatementFailedException e) {
    log.error("CQL failed at line {}: {}", e.getLineNumber(), statement, e);
    throw new AssertionError("Fix CQL statement", e);
}

Prevention

When it happens

Trigger: Calling container.executeCql(...) or the delegate's execute(String statement,...) with CQL that cqlsh/inline execution rejects; also thrown for any statement run through containerIsStarting/init flows whose exec result reports an error.

Common situations: Invalid CQL syntax; schema operations timing out on slow Cassandra startup (schema disagreement); referencing keyspaces/tables not yet created; running scripts during containerIsStarting before Cassandra is fully ready.

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

Appendix: source

Thrown at modules/cassandra/src/main/java/org/testcontainers/cassandra/CassandraDatabaseDelegate.java:76

            if (StringUtils.isBlank(statement)) {
                executeArg = "-f";
                executeArgValue = scriptPath;
            }
            cqlshCommand = ArrayUtils.addAll(cqlshCommand, executeArg, executeArgValue);

            Container.ExecResult result =
                this.container.execInContainer(ExecConfig.builder().command(cqlshCommand).build());
            if (result.getExitCode() == 0) {
                if (StringUtils.isBlank(statement)) {
                    log.info("CQL script {} successfully executed", scriptPath);
                } else {
                    log.info("CQL statement {} was applied", statement);
                }
            } else {
                if (!silentErrorLogs) {
                    log.error("CQL script execution failed with error: \n{}", result.getStderr());
                }
                throw new ScriptStatementFailedException(statement, lineNumber, scriptPath);
            }
        } catch (IOException | InterruptedException e) {
            throw new ScriptStatementFailedException(statement, lineNumber, scriptPath, e);
        }
    }

    @Override
    public void execute(
        String statement,
        String scriptPath,
        int lineNumber,
        boolean continueOnError,
        boolean ignoreFailedDrops
    ) {
        this.execute(statement, scriptPath, lineNumber, continueOnError, ignoreFailedDrops, false);
    }

    @Override

View on GitHub (pinned to 8e549514e3)