{"record":{"id":"9b93eaf6f0a3eae4","repo":"aeron-io/aeron","slug":"nodestatefile-does-not-exist-and-createnew-false","errorCode":null,"errorMessage":"NodeStateFile does not exist and createNew=false","messagePattern":"NodeStateFile does not exist and createNew=false","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/NodeStateFile.java","lineNumber":110,"sourceCode":"     * @param fileSyncLevel whether the mapped byte buffer should be synchronised with the underlying filesystem on\n     *                      change.\n     * @throws IOException if there is an error creating the file or <code>createNew == false</code> and the file does\n     * not already exist.\n     */\n    public NodeStateFile(final File clusterDir, final boolean createNew, final int fileSyncLevel) throws IOException\n    {\n        this.fileSyncLevel = fileSyncLevel;\n        final UnsafeBuffer buffer;\n        MappedByteBuffer mappedFile = null;\n\n        try\n        {\n            final File nodeStateFile = new File(clusterDir, NodeStateFile.FILENAME);\n            if (!nodeStateFile.exists())\n            {\n                if (!createNew)\n                {\n                    throw new IOException(\"NodeStateFile does not exist and createNew=false\");\n                }\n\n                mappedFile = IoUtil.mapNewFile(nodeStateFile, MINIMUM_FILE_LENGTH);\n                buffer = new UnsafeBuffer(mappedFile, 0, mappedFile.capacity());\n                buffer.verifyAlignment();\n\n                initialiseDecodersOnCreation(\n                    buffer,\n                    nodeStateHeaderDecoder,\n                    messageHeaderDecoder,\n                    candidateTermDecoder);\n\n                candidateTermIdOffset = calculateAndVerifyCandidateTermIdOffset();\n                buffer.putLongVolatile(candidateTermIdOffset, Aeron.NULL_VALUE);\n            }\n            else\n            {\n                mappedFile = IoUtil.mapExistingFile(nodeStateFile, \"NodeState\");","sourceCodeStart":92,"sourceCodeEnd":128,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/NodeStateFile.java#L92-L128","documentation":"NodeStateFile's constructor opens (and optionally creates) the cluster's node-state file in the cluster directory. When the file does not exist and createNew=false, the constructor cannot proceed and throws an IOException, since the caller explicitly forbade creating a new state file.","triggerScenarios":"Constructing NodeStateFile(clusterDir, createNew=false) against a cluster directory that has never had a node-state file written — i.e. a fresh/empty cluster dir or one where the file was deleted.","commonSituations":"Pointing the cluster dir at the wrong path; running recovery/tools against a fresh directory expecting existing state; the node-state file being deleted by cleanup scripts or lost because it was never committed to a mounted volume.","solutions":["Create the file by constructing NodeStateFile with createNew=true","Verify the clusterDir actually points at the existing cluster directory containing node.state file","Restore the missing node-state file from backup","If writing tooling, check new File(clusterDir, NodeStateFile.FILENAME).exists() first"],"exampleFix":"// before\nNodeStateFile f = new NodeStateFile(clusterDir, false);\n// after\nFile file = new File(clusterDir, NodeStateFile.FILENAME);\nNodeStateFile f = new NodeStateFile(clusterDir, !file.exists());","handlingStrategy":"validation","validationCode":"File f = new File(clusterDir, NodeStateFile.FILENAME); if (!f.exists()) { /* create with createNew=true or fix path */ }","typeGuard":null,"tryCatchPattern":"try { f = new NodeStateFile(clusterDir, false); } catch (IOException e) { f = new NodeStateFile(clusterDir, true); }","preventionTips":["Verify clusterDir path before opening","Never delete node.state from live cluster dirs","Back up the cluster directory contents"],"tags":["aeron-cluster","file","node-state","configuration"],"backgroundTag":"file-not-found","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"}