apache/cassandra · error · IllegalStateException

Gave up waiting on journal index to be ready

Error message

Gave up waiting on journal index to be ready

What it means

RangeSearchManager.maybeWait sleeps between retries while waiting for the Accord journal index to become ready. When the supplied RetryStrategy returns -1 (no more retries) on iteration i, it throws IllegalStateException 'Gave up waiting on journal index to be ready'. This indicates the journal index remained unavailable after exhausting the retry budget.

Source

Thrown at src/java/org/apache/cassandra/service/accord/journal/RangeSearchManager.java:170

        Index tableIndex = cfs.indexManager.getIndexByName(AccordKeyspace.JOURNAL_INDEX_NAME);
        RetryStrategy retry = DatabaseDescriptor.getAccord().retry_journal_index_ready.retry();
        for (int i = 0; !cfs.indexManager.isIndexQueryable(tableIndex); i++)
        {
            logger.debug("Journal index {} is not ready wait... waiting", AccordKeyspace.JOURNAL_INDEX_NAME);
            maybeWait(retry, i);
        }
    }

    /**
     * This method is here to make it easier for org.apache.cassandra.distributed.test.accord.journal.JournalAccessRouteIndexOnStartupRaceTest
     * to check when we need to do waiting
     */
    @VisibleForTesting
    private static void maybeWait(RetryStrategy retry, int i)
    {
        long waitTime = retry.computeWait(i, TimeUnit.MICROSECONDS);
        if (waitTime == -1)
            throw new IllegalStateException("Gave up waiting on journal index to be ready");
        try
        {
            TimeUnit.MICROSECONDS.sleep(waitTime);
        }
        catch (InterruptedException e)
        {
            throw new UncheckedInterruptedException(e);
        }
    }

    /**
     * When using {@link PartitionRangeReadCommand} we need to work with {@link RowFilter} which works with columns.
     * But the index doesn't care about table based queries and needs to be queried using the fields in the index, to
     * support that this enum exists.  This enum represents the fields present in the index and can be used to apply
     * filters to the index.
     */
    public enum SyntheticColumn
    {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Inspect earlier logs for the underlying reason the journal index is not becoming ready (I/O errors, corrupt files).
2. Increase the journal index readiness RetryStrategy (more attempts/longer max wait) via configuration or test harness.
3. Repair or restore the Accord journal data directory; consider wiping/rebuilding the journal if data loss is acceptable.
4. Ensure sufficient disk I/O headroom so index loading completes within the retry window.

Example fix

// before: default tight retry budget
RetryStrategy.NO_RETRY
// after: allow bounded retries with backoff
RetryStrategy.exponentialBackoff(10, TimeUnit.SECONDS.toMicros(1), TimeUnit.MINUTES.toMicros(5))

try { startAccord(); } catch (IllegalStateException e) { if (e.getMessage().contains("journal index")) { LOG.error("Journal index never became ready; check disk/IO and prior log lines for root cause"); throw e; } }

When it happens

Trigger: Starting Accord service / journal replay when the journal index fails to initialize or rebuild quickly enough; each start() call via maybeWait retries and finally aborts when computeWait returns -1.

Common situations: Slow disks or very large journal index rebuild at startup; I/O errors preventing index readiness; misconfigured retry strategy in tests (visible via @VisibleForTesting).

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

Related errors

• Cannot reset state and replay from a save point; must modify
• Stop marker is older than start marker ({stopMarker}<{startM
• Timeout waiting to exeute waiting transactions
• Could not catchup with peers
• Stop marker is older than start marker ({}<{}), so cannot as

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