aeron-io/aeron · error · IllegalStateException

Failed to write single byte to set segment file length

Error message

Failed to write single byte to set segment file length

What it means

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.

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

Example fix

// before: retrying recovery on a full disk (fails again)
archiveCtx.archiveDirContext(new FileContext("/archive"));
// after: verify capacity before recovery
if (new File("/archive").getUsableSpace() < requiredSegmentLength) {
    throw new IllegalStateException("archive partition too small");
}

Defensive patterns

Strategy: retry

Validate before calling

if (new File(archiveDir).getUsableSpace() < segmentLength) {
    throw new IllegalStateException("insufficient space in archive dir");
}

Try / catch

try {
    catalog.tryCommitSegmentLength(...);
} catch (IllegalStateException e) {
    log.error("segment length commit failed, check disk/storage: " + e.getMessage());
}

Prevention

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

When it happens

Trigger: 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.

Common situations: Archive partition full or read-only, NFS/storage flakiness, file descriptor closed unexpectedly, or concurrent modification of segment files while the catalog is recovering.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

AI-assisted analysis of aeron-io/aeron@6d60124e15 (2026-09-12). Data as JSON: /api/errors/8139448f1231946d. Report an issue: GitHub.

Appendix: source

Thrown at aeron-archive/src/main/java/io/aeron/archive/Catalog.java:1310

                    }

                    lastFragmentLength = align(frameLength, FRAME_ALIGNMENT);
                    nextFragmentOffset += lastFragmentLength;
                    bufferOffset += lastFragmentLength;
                }
            }

            final int lastFragmentOffset = nextFragmentOffset - lastFragmentLength;
            if (fragmentStraddlesPageBoundary(lastFragmentOffset, lastFragmentLength) &&
                !isValidFragment(buffer, bufferOffset - lastFragmentLength, lastFragmentLength, checksum) &&
                truncateOnPageStraddle.test(file))
            {
                final int singleByte = 1;
                segmentFileChannel.truncate(lastFragmentOffset);
                byteBuffer.put(0, (byte)0).limit(singleByte).position(0);
                if (singleByte != segmentFileChannel.write(byteBuffer, segmentFileLength - 1))
                {
                    throw new IllegalStateException("Failed to write single byte to set segment file length");
                }

                return lastFragmentOffset;
            }
            else
            {
                return nextFragmentOffset;
            }
        }
        catch (final IOException ex)
        {
            LangUtil.rethrowUnchecked(ex);
            return Aeron.NULL_VALUE;
        }
    }

    private static int readNextChunk(
        final FileChannel segment, final ByteBuffer byteBuffer, final int offset, final int limit) throws IOException

View on GitHub (pinned to 6d60124e15)