apache/cassandra · error · IllegalStateException

vectorsByKey is not initialized

Error message

vectorsByKey is not initialized

What it means

OnHeapGraph.vectorForKey looks up a vector by key in a lazily-built map (vectorsByKey). If the map was never initialized (the structure was built in postings-only mode or not yet built), the method throws IllegalStateException instead of returning null. This is an internal lifecycle guard, not a data problem.

Solutions

1. Ensure the vector index is fully built before querying (check index build status)
2. Rebuild the SAI vector index (DROP and re-CREATE the index) if it was created by an older/partial build
3. If seen in a recent query path, file/upgrade — this usually indicates an internal state bug

Example fix

null

// check index build status before querying:
// SELECT * FROM system_views.sstable_indexes WHERE index_name = '...'; // ensure built

try {
    float[] v = graph.vectorForKey(key);
} catch (IllegalStateException e) {
    // index not fully built; fall back to full scan or rebuild index
}

When it happens

Trigger: Calling vectorForKey before the graph's vectors map has been built/initialized — typically during a search that requests source vectors when the on-heap graph was constructed without them.

Common situations: Querying vector data while the index is mid-build or after a partial/failed index build; internal bug where search path accesses vectors on a postings-only graph; upgrades where per-sstable vector components are missing.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• non-finite value at vector[
• Out-of-bounds value at vector[
• [ ] Writer already finished!
• Unsupported expression during ANN index query:
• Zero vectors cannot be indexed or queried with cosine…

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

Appendix: source

Thrown at src/java/org/apache/cassandra/index/sai/disk/v1/vector/OnHeapGraph.java:286

        {
            for (int i = 0; i < vector.length; i++)
            {
                if (vector[i] != 0)
                    return;
            }
            throw new InvalidRequestException("Zero vectors cannot be indexed or queried with cosine similarity");
        }
    }

    public Collection<T> keysFromOrdinal(int node)
    {
        return postingsByOrdinal.get(node).getPostings();
    }

    public float[] vectorForKey(T key)
    {
        if (vectorsByKey == null)
            throw new IllegalStateException("vectorsByKey is not initialized");
        return vectorsByKey.get(key);
    }

    public long remove(ByteBuffer term, T key)
    {
        assert term != null && term.remaining() != 0;

        float[] vector = vectorType.composeAsFloat(term);
        VectorPostings<T> postings = postingsMap.get(vector);
        if (postings == null)
        {
            // it's possible for this to be called against a different memtable than the one
            // the value was originally added to, in which case we do not expect to find
            // the key among the postings for this vector
            return 0;
        }

        hasDeletions = true;

View on GitHub (pinned to 88fd0f6a0e)