apache/cassandra · critical · java.lang.IllegalArgumentException

Unsupported metadata version

Error message

Unsupported metadata version (%s)

What it means

Version.fromInt converts a serialized integer metadata version into the Version enum. If the integer does not correspond to any known version (values map lookup misses), it throws IllegalArgumentException. This typically means the data was produced by an incompatible Cassandra/TCM version - either too new (unknown higher version) or corrupt.

Solutions

1. Ensure all cluster nodes run a version whose metadata version is known to this build - align versions
2. If downgrade caused it, restore metadata from a backup taken at the older version or wipe and re-bootstrap from seed data
3. If data is corrupt, restore the TCM persistence files from snapshot/backup

// validate the metadata version int before deserializing
if (!knownVersions.contains(versionInt))
    throw new IllegalArgumentException("Unsupported metadata version: " + versionInt);

try { Version v = Version.fromInt(i); }
catch (IllegalArgumentException e) {
    // data from incompatible cluster version - refuse to load, alert operator
}

When it happens

Trigger: Deserializing ClusterMetadata persisted/replicated by a newer or older incompatible Cassandra version; corrupted metadata snapshot/commit log containing a bogus version int.

Common situations: Downgrade attempted after metadata version bumped; mixing node versions in a cluster beyond supported compatibility; disk corruption of TCM persistence.

Related errors

• Unable to serialize metadata snapshot triggered by…
• Addresses differ: !=
• Attempted to encode a response with an unset stream id:
• Bad CMS state:
• Bad NodeState

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

Appendix: source

Thrown at src/java/org/apache/cassandra/tcm/serialization/Version.java:161

    }

    public boolean isBefore(Version other)
    {
        return version < other.version;
    }

    public boolean isAfter(Version other)
    {
        return version > other.version;
    }

    public static Version fromInt(int i)
    {
        Version v = values.get(i);
        if (v != null)
            return v;

        throw new IllegalArgumentException("Unsupported metadata version (" + i + ")");
    }

    public List<Version> greaterThanOrEqual()
    {
        Version[] all = Version.values();
        if (ordinal() == all.length - 1)
            return Collections.singletonList(this);
        List<Version> values = new ArrayList<>(all.length - ordinal());
        for (int i = ordinal(); i < all.length; i++)
            values.add(all[i]);
        return values;
    }
}

View on GitHub (pinned to 88fd0f6a0e)