aeron-io/aeron · critical · StorageSpaceException

insufficient usable storage for new log of length=

Error message

insufficient usable storage for new log of length=<logLength> usable=<usableSpace> in <fileStore>

What it means

FileStoreLogFactory.checkStorage runs before every new publication/image log buffer allocation and throws io.aeron.exceptions.StorageSpaceException when the usable space on the data directory's file store is less than the total log length (3 * termLength padded to filePageSize). This guards against allocating large term buffers on a full disk. When usable space falls to or below the low-storage threshold, only a warning is issued, but below logLength is a hard failure.

Solutions

1. Free space on the filesystem backing aeron.data.dir (delete old publications/images directories while the driver is stopped, or clean other files).
2. Reduce aeron.term.buffer.length (and aeron.ipc.term.buffer.length) or set aeron.publication.unblock/expire streams so buffers are reclaimed.
3. Enable aeron.term.buffer.sparse.file=true to allocate sparse files that consume less real space.
4. Disable the check with aeron.driver.storage.check=false only if you can monitor space yourself; the subsequent file creation will fail anyway if the disk is truly full.
5. Move aeron.data.dir to a larger volume.

Example fix

// before
MediaDriver.Context ctx = new MediaDriver.Context()
    .termBufferLength(1 << 30); // 1GB terms -> ~3GB per log
// after
MediaDriver.Context ctx = new MediaDriver.Context()
    .termBufferLength(1 << 20)   // 1MB terms -> ~3MB per log
    .termBufferSparseFile(true);

import java.io.File;
import java.nio.file.Files;
void ensureSpace(String dataDir, long requiredBytes) throws Exception {
    long usable = Files.getFileStore(new File(dataDir).toPath()).getUsableSpace();
    if (usable < requiredBytes) {
        throw new IllegalStateException("need " + requiredBytes + " bytes, only " + usable + " usable");
    }
}
// requiredBytes = 3L * termBufferLength rounded up to filePageSize

try {
    publication = aeron.addPublication(channel, streamId);
} catch (io.aeron.exceptions.StorageSpaceException e) {
    // free disk or reduce term length, then retry
    log.error("insufficient storage: " + e.getMessage());
}

When it happens

Trigger: newPublication() or newImage() (via newInstance) is called while usableSpace < logLength: typically creating a publication/image with large termLength (e.g. 1GB terms need ~3GB) on a nearly full filesystem, with aeron.driver.storage.check enabled (default).

Common situations: Disk filled by log buffers that were never deleted (unclosed publications), default 16MB terms on a small disk/container volume, many concurrent streams exhausting space, or Docker overlay volume limits hit.

Understand the failure class

Background: "File too large" / "file size exceeds limit" errors: why libraries cap file sizes and how to fix them — this error's family across 46 libraries.

Related errors

• AgentTerminationException (storage space error on local…
• catalog is full, max capacity reached: " +…
• Failed to write single byte to set segment file length
• name + " cannot be negative: value=" + value
• ControlSession.RESPONSE_NOT_CONNECTED_MSG + ": " + session

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

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/buffer/FileStoreLogFactory.java:149

    {
        final long logLength = computeLogLength(termLength, filePageSize);
        checkStorage(logLength);

        final File location = streamLocation(rootDir, correlationId);

        return new MappedRawLog(
            location, useSparseFiles, logLength, termLength, filePageSize, errorHandler, mappedBytesCounter);
    }

    private void checkStorage(final long logLength)
    {
        if (checkStorage)
        {
            final long usableSpace = getUsableSpace();

            if (usableSpace < logLength)
            {
                throw new StorageSpaceException(
                    "insufficient usable storage for new log of length=" + logLength + " usable=" + usableSpace +
                    " in " + fileStore);
            }

            if (usableSpace <= lowStorageWarningThreshold)
            {
                final String msg =
                    "space is running low: threshold=" + lowStorageWarningThreshold +
                    " usable=" + usableSpace + " in " + fileStore;

                errorHandler.onError(new AeronException(msg, AeronException.Category.WARN));
            }
        }
    }

    private long getUsableSpace()
    {
        long usableSpace = 0;

View on GitHub (pinned to 6d60124e15)