{"record":{"id":"8139448f1231946d","repo":"aeron-io/aeron","slug":"failed-to-write-single-byte-to-set-segment-file-length","errorCode":null,"errorMessage":"Failed to write single byte to set segment file length","messagePattern":"Failed to write single byte to set segment file length","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/Catalog.java","lineNumber":1310,"sourceCode":"                    }\n\n                    lastFragmentLength = align(frameLength, FRAME_ALIGNMENT);\n                    nextFragmentOffset += lastFragmentLength;\n                    bufferOffset += lastFragmentLength;\n                }\n            }\n\n            final int lastFragmentOffset = nextFragmentOffset - lastFragmentLength;\n            if (fragmentStraddlesPageBoundary(lastFragmentOffset, lastFragmentLength) &&\n                !isValidFragment(buffer, bufferOffset - lastFragmentLength, lastFragmentLength, checksum) &&\n                truncateOnPageStraddle.test(file))\n            {\n                final int singleByte = 1;\n                segmentFileChannel.truncate(lastFragmentOffset);\n                byteBuffer.put(0, (byte)0).limit(singleByte).position(0);\n                if (singleByte != segmentFileChannel.write(byteBuffer, segmentFileLength - 1))\n                {\n                    throw new IllegalStateException(\"Failed to write single byte to set segment file length\");\n                }\n\n                return lastFragmentOffset;\n            }\n            else\n            {\n                return nextFragmentOffset;\n            }\n        }\n        catch (final IOException ex)\n        {\n            LangUtil.rethrowUnchecked(ex);\n            return Aeron.NULL_VALUE;\n        }\n    }\n\n    private static int readNextChunk(\n        final FileChannel segment, final ByteBuffer byteBuffer, final int offset, final int limit) throws IOException","sourceCodeStart":1292,"sourceCodeEnd":1328,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/Catalog.java#L1292-L1328","documentation":"Thrown when the archive catalog attempts to extend a recording's last segment file to the full segment length by writing a single zero byte at offset segmentFileLength-1, but FileChannel.write reports writing fewer bytes. This indicates the underlying file channel is in a bad state or the truncate/write semantics failed.","triggerScenarios":"Catalog recovery or segment extension hits a channel whose single-byte write at the given position does not complete — e.g. disk-full, I/O errors on the storage device, or a closed channel.","commonSituations":"Archive partition full or read-only, NFS/storage flakiness, file descriptor closed unexpectedly, or concurrent modification of segment files while the catalog is recovering.","solutions":["Check free disk space and write permissions on the archive directory/partition","Ensure no other process is modifying or holding the segment file exclusively","Check storage health (dmesg/syslog for I/O errors) and remount/replace failing disks","Retry catalog recovery after fixing storage; report to Aeron maintainers with logs if it persists on healthy storage"],"exampleFix":"// before: retrying recovery on a full disk (fails again)\narchiveCtx.archiveDirContext(new FileContext(\"/archive\"));\n// after: verify capacity before recovery\nif (new File(\"/archive\").getUsableSpace() < requiredSegmentLength) {\n    throw new IllegalStateException(\"archive partition too small\");\n}","handlingStrategy":"retry","validationCode":"if (new File(archiveDir).getUsableSpace() < segmentLength) {\n    throw new IllegalStateException(\"insufficient space in archive dir\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    catalog.tryCommitSegmentLength(...);\n} catch (IllegalStateException e) {\n    log.error(\"segment length commit failed, check disk/storage: \" + e.getMessage());\n}","preventionTips":["Monitor free disk space on the archive partition","Use local reliable storage rather than NFS for the archive directory","Prevent concurrent access to archive files from multiple processes/tools","Watch system logs for underlying I/O errors"],"tags":["aeron-archive","file-io","disk-full","catalog"],"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-15T23:17:13.987Z"}