apache/cassandra · error · InvalidRequestException

Key may not be empty

Error message

Key may not be empty

What it means

Cassandra validates every partition key supplied to CQL statements in Validation.validateKey. A null key or a key ByteBuffer with zero remaining bytes cannot identify a partition, so an InvalidRequestException is thrown before the statement is executed. This protects the storage engine from writing or reading rows with unusable keys.

Source

Thrown at src/java/org/apache/cassandra/cql3/Validation.java:49

 * Note: this hosts functions that were historically in ThriftValidation, but
 * it's not necessary clear that this is the best place to have this (this is
 * certainly not horrible either though).
 */
public abstract class Validation
{

    /**
     * Validates a (full serialized) partition key.
     *
     * @param metadata the metadata for the table of which to check the key.
     * @param key the serialized partition key to check.
     *
     * @throws InvalidRequestException if the provided {@code key} is invalid.
     */
    public static void validateKey(TableMetadata metadata, ByteBuffer key)
    {
        if (key == null || key.remaining() == 0)
            throw new InvalidRequestException("Key may not be empty");

        // check that key can be handled by ByteArrayUtil.writeWithShortLength and ByteBufferUtil.writeWithShortLength
        if (key.remaining() > FBUtilities.MAX_UNSIGNED_SHORT)
        {
            throw new InvalidRequestException("Key length of " + key.remaining() +
                                              " is longer than maximum of " +
                                              FBUtilities.MAX_UNSIGNED_SHORT);
        }

        try
        {
            metadata.partitionKeyType.validate(key);
        }
        catch (MarshalException e)
        {
            throw new InvalidRequestException(e.getMessage());
        }
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Ensure the application supplies a non-null, non-empty value for every partition key column before executing the statement.
  2. Add application-side validation rejecting rows with empty key fields before sending CQL.
  3. Check bound-variable values in the driver (e.g. a null BoundStatement field) and default or fail early.
  4. If empty keys are legitimately expected, redefine the schema so key components are meaningful (e.g. use a sentinel value or composite key).

Example fix

// before
String id = getOptionalId(); // may be ""
session.execute("INSERT INTO users (id, name) VALUES (?, ?)", id, name);
// after
String id = getOptionalId();
if (id == null || id.isEmpty()) throw new IllegalArgumentException("id must be non-empty");
session.execute("INSERT INTO users (id, name) VALUES (?, ?)", id, name);
Defensive patterns

Strategy: validation

Validate before calling

public static void validatePartitionKey(ByteBuffer key) {
    if (key == null || key.remaining() == 0)
        throw new IllegalArgumentException("Partition key must be non-null and non-empty");
}

Try / catch

try {
    session.execute(stmt);
} catch (InvalidQueryException e) {
    if (e.getMessage().contains("Key may not be empty")) {
        log.error("Empty partition key supplied; fix key generation", e);
    } else throw e;
}

Prevention

When it happens

Trigger: Executing INSERT/SELECT/DELETE/UPDATE with a partition key bound to null, an empty string/bytebuffer, or a variable-length key type (text/blob) whose serialized value has 0 remaining bytes.

Common situations: Application passes an empty string or unset variable as the primary key; a deserialization bug yields an empty buffer; driver-side null binding of a key column; ETL jobs writing rows with blank key fields.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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