apache/cassandra · error · InvalidRequestException

Table '%s.%s' doesn't exist

Error message

Table '%s.%s' doesn't exist

What it means

Thrown by AlterTableStatement.apply when the target table (or view) does not exist in the keyspace and IF EXISTS was not specified. Cassandra rejects the ALTER TABLE with an InvalidRequestException rather than silently succeeding.

Source

Thrown at src/java/org/apache/cassandra/cql3/statements/schema/AlterTableStatement.java:130

        super.validate(state);

        // save the query state to use it for guardrails validation in #apply
        this.state = state;
    }

    public Keyspaces apply(ClusterMetadata metadata)
    {
        Keyspaces schema = metadata.schema.getKeyspaces();
        KeyspaceMetadata keyspace = schema.getNullable(keyspaceName);

        TableMetadata table = null == keyspace
                            ? null
                            : keyspace.getTableOrViewNullable(tableName);

        if (null == table)
        {
            if (!ifExists)
                throw ire("Table '%s.%s' doesn't exist", keyspaceName, tableName);
            return schema;
        }

        if (table.params.pendingDrop)
            throw ire("Cannot use ALTER TABLE on a table that is being dropped.");

        if (table.isView())
            throw ire("Cannot use ALTER TABLE on a materialized view; use ALTER MATERIALIZED VIEW instead");

        return schema.withAddedOrUpdated(apply(metadata.nextEpoch(), keyspace, table, metadata));
    }

    SchemaChange schemaChangeEvent(KeyspacesDiff diff)
    {
        return new SchemaChange(Change.UPDATED, Target.TABLE, keyspaceName, tableName);
    }

    public void authorize(ClientState client)

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Verify the table exists: SELECT * FROM system_schema.tables WHERE keyspace_name = ?
  2. Add IF EXISTS to make the statement idempotent: ALTER TABLE IF EXISTS ...
  3. Fix the keyspace/table name spelling or casing

Example fix

// before
session.execute("ALTER TABLE my_app.metricss ADD description text");
// after
session.execute("ALTER TABLE IF EXISTS my_app.metrics ADD description text");
Defensive patterns

Strategy: validation

Validate before calling

Row r = session.execute("SELECT table_name FROM system_schema.tables WHERE keyspace_name=? AND table_name=?", ks, table).one();
if (r == null)
    throw new IllegalStateException("Table " + ks + "." + table + " does not exist");

Try / catch

try {
    session.execute(alter);
} catch (InvalidRequestException e) {
    if (e.getMessage().endsWith("doesn't exist"))
        log.warn("Table missing, skipping idempotent migration: {}", alter);
    else throw e;
}

Prevention

When it happens

Trigger: 'ALTER TABLE keyspace.table ...' where keyspace.getTableOrViewNullable(tableName) returns null and ifExists is false; also fires when only the keyspace exists but the table name is misspelled or was already dropped

Common situations: Migration scripts run twice after the table was dropped in a prior run; typo in table name; case sensitivity issues (unquoted identifiers lowercased by CQL); applying DDL to the wrong cluster/environment.

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

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