{"record":{"id":"1135adb7d05c3f43","repo":"apache/cassandra","slug":"found-empty-hints-file-on-startup-removing","errorCode":null,"errorMessage":"Found empty hints file {} on startup, removing","messagePattern":"Found empty hints file (.+?) on startup, removing","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"src/java/org/apache/cassandra/hints/HintsDescriptor.java","lineNumber":305,"sourceCode":"            return Optional.empty();\n        }\n    }\n\n    @VisibleForTesting\n    static void handleDescriptorIOE(IOException e, Path path)\n    {\n        try\n        {\n            if (Files.size(path) > 0)\n            {\n                String newFileName = path.getFileName().toString().replace(\".hints\", \".corrupt.hints\");\n                Path target = path.getParent().resolve(newFileName);\n                logger.error(\"Failed to deserialize hints descriptor {} - saving file as {}\", path.toString(), target, e);\n                Files.move(path, target);\n            }\n            else\n            {\n                logger.warn(\"Found empty hints file {} on startup, removing\", path.toString());\n                Files.delete(path);\n            }\n        }\n        catch (IOException ex)\n        {\n            logger.error(\"Error handling corrupt hints file {}\", path.toString(), ex);\n        }\n    }\n\n    static HintsDescriptor readFromFile(File path)\n    {\n        try (FileInputStreamPlus raf = new FileInputStreamPlus(path))\n        {\n            return deserialize(raf);\n        }\n        catch (IOException e)\n        {\n            throw new FSReadError(e, path);","sourceCodeStart":287,"sourceCodeEnd":323,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/hints/HintsDescriptor.java#L287-L323","documentation":"During hints-file discovery at startup, a descriptor that fails to deserialize is examined in handleDescriptorIOE. If the underlying file is empty (0 bytes — typically from a crash before any data was flushed), the node logs this warning and deletes the empty file. If it is non-empty but corrupt, it is renamed with a suffix instead. This is cleanup of an unusable hints file, not a data error for live data.","triggerScenarios":"HintsDescriptor.readFromFileQuietly fails on a zero-length hints file found in the hints directory at startup; the node then deletes it.","commonSituations":"Unclean shutdown (kill -9, OOM, power loss) leaving a newly created, never-written hints file; disk-full condition interrupting file creation.","solutions":["No action needed — empty hints files carry no data and are deleted automatically","If it recurs often, investigate why nodes shut down uncleanly (OOM kills, power loss, storage issues)","Check disk space on the hints volume"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// detect the condition yourself before opening descriptors\nFile f = hintsFile.toFile();\nif (f.length() == 0) {\n  f.delete(); // safe: no hints inside\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use graceful shutdown (nodetool drain) to avoid empty/partial files","Monitor for repeated empty hints files as a sign of crashes or disk-full","Keep free space on the hints volume"],"tags":["hints","startup","corruption","cleanup"],"backgroundTag":"file-not-found","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}