testcontainers/testcontainers-java · error · UncategorizedScriptException

Error while executing init script

Error message

Error while executing init script: {} + initScriptPath

What it means

When executing the init CQL script via ScriptUtils.executeDatabaseScript throws a ScriptException (a statement in the script failed to parse/execute), CassandraContainer logs 'Error while executing init script' and rethrows as ScriptUtils.UncategorizedScriptException with the script path. The container start aborts.

Solutions

  1. Fix the CQL in the init script; test it manually with cqlsh against the same image version
  2. Match the script to the container's Cassandra version (check keyspace/table names in system_schema)
  3. Check the cause chain of UncategorizedScriptException for the exact failing statement and line

Example fix

// before (init.cql)
CREATE KEYSPACE test WITH replication = {'class': 'SimpleStrategy'};
// after
CREATE KEYSPACE IF NOT EXISTS test WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 1};
Defensive patterns

Strategy: validation

Validate before calling

// Validate CQL locally before wiring the container:
// run the script against a matching Cassandra version via cqlsh or a local node

Try / catch

try { container.start(); } catch (UncategorizedScriptException e) { /* e.getCause() names the failing statement/line */ }

Prevention

When it happens

Trigger: container.start() with a valid, loadable init script whose CQL contains syntax errors, unsupported statements, or statements failing against the Cassandra node.

Common situations: CQL written for a different Cassandra version (e.g. system_schema vs system tables); invalid CREATE TABLE syntax; using directives unsupported by ScriptUtils (comment separators).

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

Appendix: source

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

    private void runInitScriptIfRequired() {
        if (initScriptPath != null) {
            try {
                URL resource = Thread.currentThread().getContextClassLoader().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 cql = IOUtils.toString(resource, StandardCharsets.UTF_8);
                DatabaseDelegate databaseDelegate = getDatabaseDelegate();
                ScriptUtils.executeDatabaseScript(databaseDelegate, initScriptPath, cql);
            } 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 ScriptUtils.UncategorizedScriptException(
                    "Error while executing init script: " + initScriptPath,
                    e
                );
            }
        }
    }

    /**
     * Map (effectively replace) directory in Docker with the content of resourceLocation if resource location is not null
     *
     * Protected to allow for changing implementation by extending the class
     *
     * @param pathNameInContainer path in docker
     * @param resourceLocation    relative classpath to resource
     */
    protected void optionallyMapResourceParameterAsVolume(String pathNameInContainer, String resourceLocation) {
        Optional
            .ofNullable(resourceLocation)

View on GitHub (pinned to 8e549514e3)