apache/cassandra · error · InvalidRequestException

Unknown column '%s' referenced in PRIMARY KEY for table '%s'

Error message

Unknown column '%s' referenced in PRIMARY KEY for table '%s'

What it means

CreateTableStatement.builder PRIMARY KEY handling: a column listed in the PRIMARY KEY clause was not declared in the column definitions, so the table cannot be built; the message names the unknown column and table.

Source

Thrown at src/java/org/apache/cassandra/cql3/statements/schema/CreateTableStatement.java:296

            {
                ((UserType) type).fieldTypes().forEach(field ->
                {
                    if (field.isMultiCell())
                        throw ire("Non-frozen UDTs with nested non-frozen collections are not supported");
                });
            }
        });

        /*
         * Deal with PRIMARY KEY columns
         */

        HashSet<ColumnIdentifier> primaryKeyColumns = new HashSet<>();
        concat(partitionKeyColumns, clusteringColumns).forEach(column ->
        {
            ColumnProperties properties = columns.get(column);
            if (null == properties)
                throw ire("Unknown column '%s' referenced in PRIMARY KEY for table '%s'", column, tableName);

            if (!primaryKeyColumns.add(column))
                throw ire("Duplicate column '%s' in PRIMARY KEY clause for table '%s'", column, tableName);

            AbstractType<?> type = properties.type;
            if (type.isMultiCell())
            {
                CQL3Type cqlType = properties.cqlType;
                if (type.isCollection())
                    throw ire("Invalid non-frozen collection type %s for PRIMARY KEY column '%s'", cqlType, column);
                else
                    throw ire("Invalid non-frozen user-defined type %s for PRIMARY KEY column '%s'", cqlType, column);
            }

            if (type.isCounter())
                throw ire("counter type is not supported for PRIMARY KEY column '%s'", column);

            if (type.referencesDuration())

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Add the missing column to the column definitions, e.g. `b text`
2. Fix the typo so the PRIMARY KEY references a declared column

Example fix

// before
CREATE TABLE t (a int, PRIMARY KEY (b));
// after
CREATE TABLE t (a int, b text, PRIMARY KEY (b));

Set<String> declared = columnNames; Set<String> referenced = primaryKeyColumns; if (!declared.containsAll(referenced)) throw new IllegalArgumentException("PRIMARY KEY references undeclared columns: " + new HashSet<>(referenced - declared));

try { session.execute(ddl); } catch (InvalidRequestException e) { if (e.getMessage().contains("referenced in PRIMARY KEY")) { /* parse the column name from the message, add or correct its declaration */ } else throw e; }

When it happens

Trigger: `CREATE TABLE t (a int PRIMARY KEY (b), c int)` — PRIMARY KEY references column 'b' that is not defined.

Common situations: Typos in column names inside PRIMARY KEY (...); refactoring column names without updating the PRIMARY KEY clause; generated DDL referencing missing columns.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• %s constraint can not be specified on a %s key column '%s'
• Cannot drop PRIMARY KEY column %s
• Duplicate column '%s' in PRIMARY KEY clause for table '%s'
• Static column '%s' cannot be part of the PRIMARY KEY
• COMPACT STORAGE with composite PRIMARY KEY allows no more th

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