apache/cassandra · error · java.lang.IllegalStateException

Missing schema, you should provide the schema for the SSTabl

Error message

Missing schema, you should provide the schema for the SSTable to create with forTable()

What it means

Thrown by CQLSSTableWriter.Builder.build() as an IllegalStateException when no schema (CREATE TABLE) statement was provided. The writer needs the table schema to construct the internal column-family metadata used to serialize rows into SSTables.

Source

Thrown at src/java/org/apache/cassandra/io/sstable/CQLSSTableWriter.java:698

        /**
         * Use specific compression dictionary upon writing the data.
         *
         * @param compressionDictionary compression dictionary to use
         * @return this builder
         */
        public Builder withCompressionDictionary(CompressionDictionary compressionDictionary)
        {
            this.compressionDictionary = compressionDictionary;
            return this;
        }

        public CQLSSTableWriter build()
        {
            if (directory == null)
                throw new IllegalStateException("No ouptut directory specified, you should provide a directory with inDirectory()");
            if (schemaStatement == null)
                throw new IllegalStateException("Missing schema, you should provide the schema for the SSTable to create with forTable()");
            if (modificationStatement == null)
                throw new IllegalStateException("No modification (INSERT/UPDATE/DELETE) statement specified, you should provide a modification statement through using()");

            Set<String> activeKeyspaces = new HashSet<>(SchemaConstants.LOCAL_SYSTEM_KEYSPACE_NAMES);

            if (!DatabaseDescriptor.getAccordTransactionsEnabled())
                activeKeyspaces.remove(SchemaConstants.ACCORD_KEYSPACE_NAME);

            Preconditions.checkState(Sets.difference(activeKeyspaces, Schema.instance.getKeyspaces()).isEmpty(),
                                     "Local keyspaces were not loaded. If this is running as a client, please make sure to add %s=true system property.",
                                     CassandraRelevantProperties.FORCE_LOAD_LOCAL_KEYSPACES.getKey());

            // Assign the default max SSTable size if not defined in builder
            if (isMaxSSTableSizeUnset())
            {
                maxSSTableSizeInMiB = sorted ? -1L : DEFAULT_BUFFER_SIZE_IN_MIB_FOR_UNSORTED;
            }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Add .forTable("CREATE TABLE ...") to the builder chain before build()
Confirm the schema variable is non-null and a valid CREATE TABLE statement
Ensure the target keyspace exists or include CREATE KEYSPACE handling before building the writer

Example fix

// before
CQLSSTableWriter writer = CQLSSTableWriter.builder()
    .inDirectory(dir).using(insert).build();
// after
CQLSSTableWriter writer = CQLSSTableWriter.builder()
    .inDirectory(dir)
    .forTable("CREATE TABLE ks.tbl (k text PRIMARY KEY, v int)")
    .using(insert).build();

Defensive patterns

Strategy: validation

Validate before calling

if (schemaCql == null || schemaCql.isEmpty()) throw new IllegalStateException("forTable() schema required before build()");

Type guard

null

Try / catch

try { writer = builder.build(); } catch (IllegalStateException e) { if (e.getMessage().contains("schema")) { /* supply forTable() and rebuild */ } throw e; }

Prevention

Always pair forTable() and using() in a shared writer-factory method
Validate the CREATE TABLE parses (e.g. via a quick CQL parse) before building
Keep schema strings in version-controlled constants, not inline literals scattered in code

When it happens

Trigger: Calling build() without invoking forTable(...) on the Builder.

Common situations: Assembling builder options from variables where the schema string failed to be set (null/empty branch); reordering builder code so build() runs before forTable; generating writers in a loop where one iteration skips the schema setup.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/2c73d3df434274ac. Report an issue: GitHub.