apache/cassandra · error · ConfigurationException

. : Keyspace name must not be empty

Error message

%s.%s: Keyspace name must not be empty

What it means

Thrown as a ConfigurationException by the TableMetadata.Builder when building a table without a keyspace set. A table definition is meaningless without its parent keyspace, so construction fails early rather than producing a broken TableMetadata.

Solutions

1. Call keyspace("<name>") on the builder before build()
2. Parse DDL through the schema statement machinery so keyspace is set from context
3. Assert builder state in helper methods that wrap table construction
4. Set a default keyspace in the utility that creates builders

Example fix

// before
TableMetadata t = TableMetadata.builder().name("users").addPartitionKeyColumn("id", UUIDType.instance).build();
// after
TableMetadata t = TableMetadata.builder().keyspace("my_ks").name("users").addPartitionKeyColumn("id", UUIDType.instance).build();

assert builder != null; // ensure keyspace was set: track it in a wrapper around TableMetadata.builder()

TableMetadata.Builder requireKeyspace(TableMetadata.Builder b, String ks) { if (ks == null || ks.isEmpty()) throw new IllegalArgumentException("keyspace required"); return b.keyspace(ks); }

try { TableMetadata t = builder.build(); ... } catch (ConfigurationException e) { throw new IllegalStateException("Table builder misconfigured: " + e.getMessage(), e); }

When it happens

Trigger: Calling TableMetadata.builder() ... build() without invoking builder().keyspace(ksName) — usually from programmatic schema construction (tools, tests, virtual table implementations).

Common situations: Programmatic table builders missing the keyspace() call; refactors that reorder builder calls and drop keyspace(); test fixtures constructing tables directly instead of via parsed DDL.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• ACCESS TO DATACENTERS operations not supported by…
• ALREADY_EXISTS
• Already exists
• Because of this name
• Cannot add new field

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

Appendix: source

Thrown at src/java/org/apache/cassandra/schema/TableMetadata.java:1012

        private boolean assignUniqueIds = false;

        private Builder(String keyspace, String name, TableId id)
        {
            this.keyspace = keyspace;
            this.name = name;
            this.id = id;
        }

        private Builder(String keyspace, String name)
        {
            this.keyspace = keyspace;
            this.name = name;
        }

        public TableMetadata build()
        {
            if (keyspace == null)
                throw new ConfigurationException(keyspace + '.' + name + ": Keyspace name must not be empty");
            if (partitioner == null)
                partitioner = DatabaseDescriptor.getPartitioner();

            if (id == null)
            {
                // make sure vtables use deteriminstic ids so they can be referenced in calls cross-nodes
                // see CASSANDRA-17295
                if (kind == Kind.VIRTUAL)
                    id = TableId.unsafeDeterministic(keyspace, name);
                else
                    id = TableId.generate();
            }

            if (assignUniqueIds)
            {
                int nextId = Math.max(0, maxAssignedUniqueId + 1);
                for (int i = 0 ; i < partitionKeyColumns.size() ; ++i)
                {

View on GitHub (pinned to 88fd0f6a0e)