{"record":{"id":"8a389c33d7cc1c75","repo":"apache/cassandra","slug":"fsreaderror","errorCode":null,"errorMessage":"FSReadError","messagePattern":"FSReadError","errorType":"exception","errorClass":"FSReadError","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/hints/HintsReader.java","lineNumber":309,"sourceCode":"\n                if (input.isEOF())\n                    return endOfData(); // reached EOF\n\n                if (position.subtract(offset) >= PAGE_SIZE)\n                    return endOfData(); // read page size or more bytes\n\n                try\n                {\n                    buffer = computeNextInternal();\n                }\n                catch (EOFException e)\n                {\n                    logger.warn(\"Unexpected EOF replaying hints ({}), likely due to unflushed hint file on shutdown; continuing\", descriptor.fileName(), e);\n                    return endOfData();\n                }\n                catch (IOException e)\n                {\n                    throw new FSReadError(e, file);\n                }\n            }\n            while (buffer == null);\n\n            return buffer;\n        }\n\n        private ByteBuffer computeNextInternal() throws IOException\n        {\n            input.resetCrc();\n            input.resetLimit();\n\n            int size = input.readInt();\n            if (size == 0)\n            {\n                // Avoid throwing IOException when a hint file ends with a run of zeros - this\n                // can happen when hard-rebooting unresponsive machines.\n                if (!verifyAllZeros(input))","sourceCodeStart":291,"sourceCodeEnd":327,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/hints/HintsReader.java#L291-L327","documentation":"FSReadError is Cassandra's wrapper for unexpected filesystem read failures, thrown in HintsReader.computeNext when reading a hint file raises an IOException that is not a benign EOF. It indicates the hints file on disk cannot be read (I/O error rather than a truncated/zero-filled tail).","triggerScenarios":"Reading hints files during hint replay when the underlying file read fails: disk errors, permission problems, file deleted/renamed underneath the reader, or checksum-region reads throwing IOException.","commonSituations":"Failing disk or bad sector in the hints directory; hints file removed by an external cleanup script while replay is in progress; permissions changed on the hints directory; NFS/storage faults.","solutions":["Check the node's system.log for the wrapped IOException cause and the file name, and inspect disk health (dmesg, smartctl)","Verify permissions and existence of files in the hints directory (hinted_handoff directory, default /var/lib/cassandra/hints)","If the file is corrupt, move the offending hints file out of the hints directory and restart replay","Restore from backup or let other replicas' hints/divergence-repair (e.g. repair) cover the data"],"exampleFix":"// before: failing hard on unreadable hint file\n// move the unreadable file aside instead\nmv /var/lib/cassandra/hints/<uuid>-1-1.hints /tmp/bad_hints/\n// then restart the node or re-trigger dispatch","handlingStrategy":"try-catch","validationCode":"File dir = new File(hintsDir);\nif (!dir.canRead() || !dir.isDirectory()) throw new IllegalStateException(\"hints dir unreadable\");","typeGuard":"boolean isReadableHintsFile(File f) { return f != null && f.isFile() && f.canRead(); }","tryCatchPattern":"try { reader.readNext(); } catch (FSReadError e) { logger.error(\"Hints read failed\", e); file.renameTo(new File(file + \".corrupt\")); }","preventionTips":["Monitor disk health on the hints volume","Keep hints on local storage","No external deletion of hints files","Run repair after replay failure"],"tags":["io","filesystem","hints","replay"],"backgroundTag":"file-read-failed","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}