{"record":{"id":"7cd5dc2e7b89fd15","repo":"aeron-io/aeron","slug":"failed-to-find-nodestatefooter-entry-file-corrupt","errorCode":null,"errorMessage":"failed to find NodeStateFooter entry, file corrupt?","messagePattern":"failed to find NodeStateFooter entry, file corrupt\\?","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/NodeStateFile.java","lineNumber":191,"sourceCode":"            buffer, 0, NodeStateHeaderDecoder.BLOCK_LENGTH, NodeStateHeaderDecoder.SCHEMA_VERSION);\n\n        final int version = nodeStateHeaderDecoder.version();\n        if (ClusterMarkFile.MAJOR_VERSION != SemanticVersion.major(version))\n        {\n            throw new ClusterException(\n                \"mark file major version \" + SemanticVersion.major(version) +\n                \" does not match software: \" + ClusterMarkFile.MAJOR_VERSION);\n        }\n\n        final int footerOffset = scanForMessageTypeOffset(\n            nodeStateHeaderDecoder.sbeBlockLength(),\n            NodeStateFooterDecoder.TEMPLATE_ID,\n            buffer,\n            messageHeaderDecoder);\n\n        if (Aeron.NULL_VALUE == footerOffset)\n        {\n            throw new IllegalStateException(\"failed to find NodeStateFooter entry, file corrupt?\");\n        }\n\n        final int candidateTermOffset = scanForMessageTypeOffset(\n            nodeStateHeaderDecoder.sbeBlockLength(),\n            CandidateTermDecoder.TEMPLATE_ID,\n            buffer,\n            messageHeaderDecoder);\n\n        if (Aeron.NULL_VALUE == candidateTermOffset)\n        {\n            throw new IllegalStateException(\"failed to find CandidateTerm entry\");\n        }\n\n        candidateTermDecoder.wrapAndApplyHeader(buffer, candidateTermOffset, messageHeaderDecoder);\n    }\n\n    private static void initialiseDecodersOnCreation(\n        final MutableDirectBuffer buffer,","sourceCodeStart":173,"sourceCodeEnd":209,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/NodeStateFile.java#L173-L209","documentation":"After validating the header, loadInitialState scans the node-state file for a NodeStateFooter message to locate the remaining entries. If no footer entry exists (scan returns Aeron.NULL_VALUE), the file layout cannot be trusted and an IllegalStateException ('file corrupt?') is thrown.","triggerScenarios":"Loading a node-state file that is truncated, partially written (e.g. crash mid-write), zero-length, or written by an incompatible writer that omitted the footer entry.","commonSituations":"Disk-full or power-loss during a node-state write; manually edited/truncated cluster files; restoring an incomplete backup of the cluster directory.","solutions":["Restore the node-state file from a known-good backup","Delete the corrupt file and recreate it with createNew=true (loses prior state: candidate term etc.)","Check the file size vs MINIMUM_FILE_LENGTH to confirm truncation before opening","Enable fsync/durable storage checks if crashes repeatedly corrupt the cluster dir"],"exampleFix":"// before\nNodeStateFile f = new NodeStateFile(clusterDir, false);\n// after\nif (new File(clusterDir, NodeStateFile.FILENAME).length() < NodeStateFile.MINIMUM_FILE_LENGTH) {\n    new File(clusterDir, NodeStateFile.FILENAME).delete();\n}\nNodeStateFile f = new NodeStateFile(clusterDir, true);","handlingStrategy":"try-catch","validationCode":"File f = new File(clusterDir, NodeStateFile.FILENAME); if (f.length() < NodeStateFile.MINIMUM_FILE_LENGTH) { /* restore backup or recreate */ }","typeGuard":null,"tryCatchPattern":"try { f.loadInitialState(); } catch (IllegalStateException e) { /* restore from backup or recreate node-state file */ }","preventionTips":["Use durable storage and clean shutdowns for the cluster dir","Verify backups are complete before restoring","Monitor for truncated cluster files after crashes"],"tags":["aeron-cluster","corruption","file","node-state"],"backgroundTag":"corrupt-file","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}