apache/cassandra · critical · IllegalArgumentException

ComponentMetadata not found

Error message

 ComponentMetadata not found

What it means

IllegalArgumentException thrown by SegmentMetadata.ComponentMetadata.get when the requested IndexComponent has no metadata entry in the segment. Each segment's metadata must contain a ComponentMetadata for every component the reader needs (balanced tree, posting lists, terms, etc.); a miss means the segment was written without that component or the wrong component was requested.

Source

Thrown at src/java/org/apache/cassandra/index/sai/disk/v1/segment/SegmentMetadata.java:273

        {
            metas.put(indexComponent, new ComponentMetadata(root, offset, length, additionalMap));
        }

        private void write(IndexOutput output) throws IOException
        {
            output.writeInt(metas.size());

            for (Map.Entry<IndexComponent, ComponentMetadata> entry : metas.entrySet())
            {
                output.writeString(entry.getKey().name());
                entry.getValue().write(output);
            }
        }

        public ComponentMetadata get(IndexComponent indexComponent)
        {
            if (!metas.containsKey(indexComponent))
                throw new IllegalArgumentException(indexComponent + " ComponentMetadata not found");

            return metas.get(indexComponent);
        }

        public Map<String, Map<String, String>> asMap()
        {
            Map<String, Map<String, String>> metaAttributes = new HashMap<>();

            for (Map.Entry<IndexComponent, ComponentMetadata> entry : metas.entrySet())
            {
                String name = entry.getKey().name();
                ComponentMetadata metadata = entry.getValue();

                Map<String, String> componentAttributes = metadata.asMap();

                assert !metaAttributes.containsKey(name) : "Found duplicate index type: " + name;
                metaAttributes.put(name, componentAttributes);
            }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. REBUILD the secondary index (or scrub/recompact the SSTable) to regenerate complete segment metadata
2. Verify the index files belong to the same segment generation and version; restore consistent files from backup
3. Check the SAI version that wrote the index matches the running node's reader version
4. If a code path requests an optional component, call contains()/check existence before get()

Example fix

// before
ComponentMetadata meta = metas.get(IndexComponent.POSTING_LISTS); // get() throws if absent
// after
if (metas.containsKey(IndexComponent.POSTING_LISTS))
{
    ComponentMetadata meta = metas.get(IndexComponent.POSTING_LISTS);
}
else
{
    logger.warn("Segment {} lacks POSTING_LISTS metadata; skipping", segment);
}

if (!componentMetas.containsKey(indexComponent)) {
    logger.warn("Segment {} missing metadata for {}; rebuilding index", segment, indexComponent);
    rebuildIndex();
}

boolean hasComponentMetadata(ComponentMetadataHolder holder, IndexComponent c) {
    return holder != null && holder.contains(c);
}

try {
    ComponentMetadata meta = metas.get(indexComponent);
} catch (IllegalArgumentException e) {
    logger.error("Segment metadata incomplete: {}", e.getMessage());
    rebuildIndex();
}

When it happens

Trigger: Calling get() with an IndexComponent absent from the metas map, e.g. reading a legacy/corrupted segment that lacks POSTING_LISTS or BALANCED_TREE metadata, or code requesting a component not written for that segment type.

Common situations: Corrupted or truncated index metadata, opening index files written by a different Cassandra/SAI version, mixing component files across segments, or custom/patched readers asking for extra components.

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

• 'null' deserialized value for %s with %s
• Error initializing OnDiskOrdinalsMap at segment
• Corrupt flags value for clustering prefix (isStatic flag set
• Invalid Columns subset bytes; too many bits set:<encoded>
• Cannot safely construct descriptor for segment, either from

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