apache/cassandra · error · JournalReadError

JournalReadError(descriptor, file, e)

Error message

JournalReadError(descriptor, file, e)

What it means

StaticSegment.Reader.doAdvance catches IOException while deserializing entries and wraps it in JournalReadError, associating the failure with the segment descriptor and file. This marks the segment unreadable at that position so callers can apply recovery policy (skip or fail).

Source

Thrown at src/java/org/apache/cassandra/journal/StaticSegment.java:470

                    switch (crcFailurePolicy)
                    {
                        case IGNORE: break;
                        case IGNORE_ALL_ZERO_RECORDS:
                            if (areAllBytesZero(buffer, offset + Integer.BYTES, e.knownLength - Integer.BYTES))
                                break;
                        case IGNORE_CRC_ZERO_RECORDS:
                            if (e.readCrc == 0)
                                break;
                        case FAIL:
                            throw new JournalReadError(descriptor, file, e.getCause());
                    }

                    logger.warn("Caught a recoverable journal error, skipping bytes", e);
                    buffer.position(offset + e.knownLength);
                }
                catch (IOException e)
                {
                    throw new JournalReadError(descriptor, file, e);
                }
            }
        }

        private void reset()
        {
            offset = -1;
            holder.clear();
            state = State.RESET;
        }
    }

    public static boolean areAllBytesZero(ByteBuffer buffer, int start, int length)
    {
        int mod8 = (length/8) * 8;
        // Make sure all bytes are zero
        for (int i = 0; i < mod8; i += Long.BYTES)
        {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Inspect the wrapped IOException cause; if recoverable, the configured RecoverableCrcFailurePolicy may skip the bad bytes
2. Run journal reserialization/recovery to rebuild or drop the corrupt segment
3. Check filesystem/disk health on the journal volume
4. Restore the segment from a snapshot taken before the corruption

// verify CRC of segment tail before full iteration, or use the configured failure policy to pre-scan
preScan(descriptor, crcFailurePolicy);

try { reader.advance(); } catch (JournalReadError e) { if (e.getCause() instanceof IOException) applyRecoveryPolicy(e); else throw e; }

When it happens

Trigger: IOException during buffer advance/entry parsing — corrupt entry bytes, unexpected EOF within an entry, or I/O errors reading the mapped file (e.g. underlying storage failure).

Common situations: Torn writes after a crash; disk corruption on the journal volume; reading segments transferred incompletely between nodes.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• Could not compact segments: " + toCompact
• {} could not replay save point {}
• Corrupt flags value for clustering prefix (isStatic flag set
• Invalid Columns subset bytes; too many bits set:<encoded>
• Corrupted sstable. Invalid flags found deserializing Deletio

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