apache/cassandra · error · RuntimeException

Failed to read log entries

Error message

Failed to read log entries

What it means

OfflineClusterMetadataDump reads ClusterMetadata log segment files from disk without a running cluster. If any IOException occurs while iterating/reading log entries to build a LogState, getLogState wraps it in a RuntimeException with this message and the original exception as cause.

Source

Thrown at src/java/org/apache/cassandra/tools/OfflineClusterMetadataDump.java:434

                                        " exceeds max available epoch " + maxAvailableEpoch);
                    }
                }

                // Warn if there's a gap between snapshot and first entry
                ClusterMetadata effectiveBase = base;
                if (effectiveBase != null && !entryList.isEmpty() && !entryList.get(0).epoch.isDirectlyAfter(effectiveBase.epoch))
                {
                    out.err.println("WARNING: Gap between snapshot (epoch " + effectiveBase.epoch.getEpoch() +
                                    ") and first log entry (epoch " + entryList.get(0).epoch.getEpoch() +
                                    "). Proceeding without base snapshot.");
                    effectiveBase = null;
                }

                return new LogState(effectiveBase, entryList);
            }
            catch (IOException e)
            {
                throw new RuntimeException("Failed to read log entries", e);
            }
        }

        static private Epoch previousEpoch(Epoch epoch)
        {
            if (UPGRADE_GOSSIP.equals(epoch) || UPGRADE_STARTUP.equals(epoch))
                return epoch;
            if (EMPTY.equals(epoch) || FIRST.equals(epoch))
                return EMPTY;
            return Epoch.create(epoch.getEpoch() - 1);
        }

        /**
         * Validates that the from-epoch is not greater than to-epoch.
         */
        protected void validateEpochRange(Long fromEpoch, Long toEpoch)
        {
            if (fromEpoch != null && toEpoch != null && fromEpoch > toEpoch)

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Check the cause in the stack trace and fix the underlying I/O problem (missing file, permissions)
2. Run the tool against the correct node data directory containing the metadata log segments
3. Verify file read permissions for the user running the tool
4. Restore the missing/corrupt segments from a healthy replica or backup

File dir = new File(dataDir);
if (!dir.isDirectory() || !dir.canRead()) throw new IllegalStateException("Cannot read log dir: " + dataDir);

try { LogState s = dump.getLogState(...); }
catch (RuntimeException e) {
    if (e.getCause() instanceof IOException) LOG.error("log read failed: " + e.getCause(), e);
    throw e;
}

When it happens

Trigger: Calling the offline metadata dump tool when the metadata log segment files are missing, unreadable (permissions), truncated, or on a filesystem error; also on disk I/O failures while scanning the commit log/metadata log directory.

Common situations: Pointing the tool at the wrong data directory so log files are absent; copying data dirs without the metadata log segments; running as a user without read permission on the files; corrupted/truncated segments after a crash.

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

• Cannot remove temporary or obsoleted files for %s.%s due to
• Unknown keyspace/table %s.%s
• Cannot remove temporary or obsoleted files for %s.%s due to
• Unknown kind in sstable
• Error reading key %s in segment %s at position %d: %s

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