apache/cassandra · warning

Found empty hints file

Error message

Found empty hints file {} on startup, removing

What it means

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.

Solutions

1. No action needed — empty hints files carry no data and are deleted automatically
2. If it recurs often, investigate why nodes shut down uncleanly (OOM kills, power loss, storage issues)
3. Check disk space on the hints volume

// detect the condition yourself before opening descriptors
File f = hintsFile.toFile();
if (f.length() == 0) {
  f.delete(); // safe: no hints inside
}

When it happens

Trigger: HintsDescriptor.readFromFileQuietly fails on a zero-length hints file found in the hints directory at startup; the node then deletes it.

Common situations: Unclean shutdown (kill -9, OOM, power loss) leaving a newly created, never-written hints file; disk-full condition interrupting file creation.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• Corrupt hint file found
• Corrupt HintsDescriptor serialization, problem:
• Corrupted key cache. Failed to deserialize key of key cache…
• Corrupted key cache. Key length of
• Digest mismatch exception

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

Appendix: source

Thrown at src/java/org/apache/cassandra/hints/HintsDescriptor.java:305

            return Optional.empty();
        }
    }

    @VisibleForTesting
    static void handleDescriptorIOE(IOException e, Path path)
    {
        try
        {
            if (Files.size(path) > 0)
            {
                String newFileName = path.getFileName().toString().replace(".hints", ".corrupt.hints");
                Path target = path.getParent().resolve(newFileName);
                logger.error("Failed to deserialize hints descriptor {} - saving file as {}", path.toString(), target, e);
                Files.move(path, target);
            }
            else
            {
                logger.warn("Found empty hints file {} on startup, removing", path.toString());
                Files.delete(path);
            }
        }
        catch (IOException ex)
        {
            logger.error("Error handling corrupt hints file {}", path.toString(), ex);
        }
    }

    static HintsDescriptor readFromFile(File path)
    {
        try (FileInputStreamPlus raf = new FileInputStreamPlus(path))
        {
            return deserialize(raf);
        }
        catch (IOException e)
        {
            throw new FSReadError(e, path);

View on GitHub (pinned to 88fd0f6a0e)