{"record":{"id":"4f9048cd30665bea","repo":"aeron-io/aeron","slug":"unable-to-create-node-state-file","errorCode":null,"errorMessage":"unable to create node-state file","messagePattern":"unable to create node-state file","errorType":"exception","errorClass":"ClusterException","httpStatus":null,"severity":"error","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/ConsensusModule.java","lineNumber":1845,"sourceCode":"                    epochClock,\n                    ClusteredServiceContainer.Configuration.LIVENESS_TIMEOUT_MS,\n                    filePageSize);\n            }\n\n            MarkFile.ensureMarkFileLink(\n                clusterDir,\n                new File(markFile.parentDirectory(), ClusterMarkFile.FILENAME),\n                ClusterMarkFile.LINK_FILENAME);\n\n            if (null == nodeStateFile)\n            {\n                try\n                {\n                    nodeStateFile = new NodeStateFile(clusterDir, true, fileSyncLevel());\n                }\n                catch (final IOException ex)\n                {\n                    throw new ClusterException(\"unable to create node-state file\", ex);\n                }\n            }\n\n            if (Aeron.NULL_VALUE == nodeStateFile.candidateTerm().candidateTermId() &&\n                Aeron.NULL_VALUE != markFile.candidateTermId())\n            {\n                nodeStateFile.updateCandidateTermId(markFile.candidateTermId(), Aeron.NULL_VALUE, epochClock.time());\n            }\n\n            if (null == errorLog)\n            {\n                errorLog = new DistinctErrorLog(markFile.errorBuffer(), epochClock, StandardCharsets.US_ASCII);\n            }\n\n            errorHandler = CommonContext.setupErrorHandler(errorHandler, errorLog);\n\n            if (null == recordingLog)\n            {","sourceCodeStart":1827,"sourceCodeEnd":1863,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/ConsensusModule.java#L1827-L1863","documentation":"If no NodeStateFile is supplied, conclude() creates one in the cluster directory to persist candidate-term state. An IOException from that file creation (missing/unwritable directory, disk full, leftover file permissions) is wrapped as ClusterException \"unable to create node-state file\".","triggerScenarios":"NodeStateFile constructor throws IOException during conclude() — cluster directory does not exist or is not writable, disk full, or filesystem errors when opening/creating the node state file.","commonSituations":"clusterDir on a read-only mount or bind-mounted volume with wrong ownership; running in a container as a non-root user without write access to /var/lib/aeron or similar; disk quota exhausted; clusterDir pointing at a file instead of a directory.","solutions":["Ensure the cluster directory exists and is writable by the process user (chown/chmod)","Check free disk space and quotas","Point ctx.clusterDir(...) at a valid writable path","Investigate the cause IOException in the exception chain for the exact OS error"],"exampleFix":"// before\nctx.clusterDir(new File(\"/mnt/readonly/cluster\"));\n// after\nFile dir = new File(\"/var/lib/aeron/cluster\");\ndir.mkdirs(); // ensure writable\nctx.clusterDir(dir);","handlingStrategy":"try-catch","validationCode":"File dir = ctx.clusterDir() != null ? ctx.clusterDir() : new File(ctx.clusterDirectoryName());\nif (!dir.isDirectory() || !dir.canWrite()) {\n    throw new IllegalStateException(\"cluster dir not writable: \" + dir);\n}","typeGuard":null,"tryCatchPattern":"try { ctx.conclude(); } catch (ClusterException e) { if (\"unable to create node-state file\".equals(e.getMessage())) { log.error(\"check cluster dir permissions/disk\", e.getCause()); } }","preventionTips":["Provision the cluster directory with correct ownership before launch","Monitor disk space on the cluster volume","In containers, mount the cluster dir with read-write and a matching UID"],"tags":["filesystem","io","persistence"],"backgroundTag":"file-write-failed","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"}