apache/cassandra · error · UnknownTableException

Unknown table

Error message

Unknown table

What it means

Thrown when deserializing a TableMetadatas payload: the table id read off the wire maps to a null slot in the decoded metadata array, meaning the peer referenced a table this node does not know about. It is raised as UnknownTableException to signal the Accord replication layer that a coordinator has knowledge of a table the local node lacks, typically during topology churn.

Solutions

1. Ensure schema agreement before running Accord workloads (check system_schema tables agree across nodes).
2. Force a schema refresh on the lagging node (nodetool resetlocalschema or re-running schema pull).
3. Retry the operation after the node catches up on schema; the transaction should be re-coordinated once the table metadata is known.
4. If the table was intentionally dropped, clear stale in-flight Accord state referencing the dropped table id.

// before coordinating Accord work, check schema agreement
Set<String> schemas = nodes.stream().map(n -> fetchSchemaVersion(n)).collect(Collectors.toSet());
if (schemas.size() > 1) throw new IllegalStateException("schema disagreement: " + schemas);

try {
    TableMetadata metadata = serializer.deserialize(in, version);
} catch (UnknownTableException e) {
    logger.warn("Peer referenced unknown table {} - refreshing schema", e.tableId);
    Schema.instance.updateLocalSchema(); // then retry the operation
}

When it happens

Trigger: Accord deserialize() reads an unsigned VInt index into the metadatas array and the slot is null because the serialized table id list contains a table id not present in this node's schema.

Common situations: Rolling upgrades or restarts where a node's schema is lagging behind the coordinator's; a table dropped on the coordinator but still referenced by in-flight Accord transactions on this node; schema disagreement across the cluster.

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

• Cannot serialize RedundantStatus larger than 0xFFFF…
• Corrupted input: expected byte 1, 2, 3, 4, 5 or 6; received
• Corrupted input: expected byte 1, 2, 3, 4 or 5; received
• Corrupted input: expected byte 1 or 2, received " + b
• No serializer exists for kind

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

Appendix: source

Thrown at src/java/org/apache/cassandra/service/accord/serializers/TableMetadatas.java:370

        @Override
        public void serializeSelf(DataOutputPlus out) throws IOException
        {
            out.writeUnsignedVInt32(ids.length);
            for (TableId id : ids)
                id.serializeCompactComparable(out);
        }

        @Override
        public TableMetadata deserialize(DataInputPlus in) throws IOException
        {
            if (ids.length == 1)
                return metadatas[0];

            int index = in.readUnsignedVInt32();
            TableMetadata metadata = metadatas[index];
            if (metadata == null)
                throw new UnknownTableException("Unknown table", ids[index]);
            return metadata;
        }

        @Override
        public long serializedSize(TableMetadata table)
        {
            if (ids.length == 1)
                return 0;

            int i = indexOf(table);
            if (i < 0)
                throw new IllegalStateException("TableMetadata for " + table + " not found in " + this);
            return TypeSizes.sizeofUnsignedVInt(indexOf(table));
        }

        @Override
        public long serializedSelfSize()
        {

View on GitHub (pinned to 88fd0f6a0e)