Unexpected EOF replaying hints

Error message

Unexpected EOF replaying hints ({}), likely due to unflushed hint file on shutdown; continuing

What it means

While iterating a hints file, the reader hit an EOFException in the middle of computing the next hint. Cassandra treats a truncated tail as expected when a node was shut down before flushing the hints file completely, so it logs this warning, stops replay of that file, and continues rather than throwing. Data loss is limited to the unflushed tail.

Solutions

No action needed if shutdown was abrupt — this is the designed recovery path
If it happens on files that should be complete, check for disk/storage errors and verify file sizes vs. descriptor
Reduce risk by using graceful shutdown (nodetool drain / stop) so files are flushed

Defensive patterns

Strategy: try-catch

Validate before calling

// verify hints file tail before replaying (basic sanity)
long fileSize = Files.size(path);
if (fileSize < HintsDescriptor.ENCODED_SIZE)
  throw new IOException("hints file too small: " + path);

Try / catch

try {
  hint = computeNextInternal();
} catch (EOFException e) {
  logger.warn("Truncated hints file {}, stopping replay", descriptor.fileName());
  return endOfData(); // accept partial replay
}

Prevention

Shut down nodes gracefully so hint files are flushed
Investigate repeated EOF warnings — could be storage-level truncation
Back up hints directory only when the node is stopped

When it happens

Trigger: computeNext → computeNextInternal raises EOFException because the file ends mid-record — unflushed hint file from an abrupt shutdown, or a truncated file.

Common situations: kill -9 / crash / power loss with hints not yet flushed; storage-level truncation; reading a hints file copied mid-write.

Related errors

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

Appendix: source

Thrown at src/java/org/apache/cassandra/hints/HintsReader.java:198

            Hint hint;

            do
            {
                InputPosition position = input.getSeekPosition();

                if (input.isEOF())
                    return endOfData(); // reached EOF

                if (position.subtract(offset) >= PAGE_SIZE)
                    return endOfData(); // read page size or more bytes

                try
                {
                    hint = computeNextInternal();
                }
                catch (EOFException e)
                {
                    logger.warn("Unexpected EOF replaying hints ({}), likely due to unflushed hint file on shutdown; continuing", descriptor.fileName(), e);
                    return endOfData();
                }
                catch (IOException e)
                {
                    throw new FSReadError(e, file);
                }
            }
            while (hint == null);

            return hint;
        }

        private Hint computeNextInternal() throws IOException
        {
            input.resetCrc();
            input.resetLimit();

            int size = input.readInt();

View on GitHub (pinned to 88fd0f6a0e)