aeron-io/aeron · error · ArchiveException

recording is too big: total recording length is " +…

Error message

recording is too big: total recording length is " + frameLength + " bytes," + " available space is " + (maxCatalogCapacity - recordingOffset) + " bytes

What it means

Thrown by Aeron Archive's Catalog when extending the catalog file to record a new recording fails because the catalog file has run out of space. Distinguishes two cases: the catalog has hit its absolute max capacity, or the remaining space is smaller than the recording length being appended. The catalog file is preallocated, so a recording whose descriptor entry would not fit cannot be accepted.

Solutions

Archive fewer/shorter recordings or let completed recordings be culled (ArchiveTool) so catalog entries no longer accumulate
Increase the catalog max capacity via Archive.Configuration.MAX_CATALOG_CAPACITY (archive --max-catalog-capacity or context.archiveCatalogCapacity()) so the file can grow or fit entries
Migrate to a fresh catalog directory: run ArchiveTool to extract/verify recordings, then start a new catalog
Set a recording-length limit in your application before requesting recordings so frameLength fits available space

Example fix

// before
Archive.Context ctx = new Archive.Context(); // default max catalog capacity
// after
Archive.Context ctx = new Archive.Context()
    .maxCatalogCapacity(1024L * 1024L * 1024L * 8L); // 8GB catalog

Defensive patterns

Strategy: validation

Validate before calling

// Before configuring the archive, estimate entries and set capacity accordingly.
long expectedRecordings = 100_000;
long minCapacity = expectedRecordings * 512; // conservative bytes per catalog entry
long maxCapacity = new Archive.Context().maxCatalogCapacity();
if (maxCapacity - 1024 < minCapacity) {
    throw new IllegalStateException("catalog capacity " + maxCapacity +
        " too small for " + expectedRecordings + " recordings");
}

Try / catch

try {
    archive.start();
} catch (ArchiveException e) {
    if (e.getMessage().contains("catalog is full") || e.getMessage().contains("recording is too big")) {
        // alert ops to grow/migrate the catalog, then reconfigure with larger maxCatalogCapacity
    } else {
        throw e;
    }
}

Prevention

Size maxCatalogCapacity for your expected recording count plus headroom (each entry consumes ~hundreds of bytes)
Monitor catalog file size growth and alert before it approaches capacity
Periodically cull completed recordings with ArchiveTool
Keep recording lengths bounded relative to remaining catalog space

When it happens

Trigger: Appending a new recording descriptor (Catalog.addNewRecording / first recording of a session) when recordingOffset + frameLength exceeds maxCatalogCapacity; also triggered by forceGrowCatalog when growing is impossible because oldCapacity == maxCatalogCapacity.

Common situations: Long-running archives with many short recordings accumulating thousands of catalog entries; a catalog file sized with too small a --max-catalog-capacity (default ~1GB) relative to expected recording count; reusing a catalog across many replay/recording cycles until entries exhaust it.

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

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

Appendix: source

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

            return -1;
        }
        return (int)recordingDescriptorOffset;
    }

    void growCatalog(final long maxCatalogCapacity, final int frameLength)
    {
        final long oldCapacity = capacity;
        final long recordingOffset = nextRecordingDescriptorOffset;
        final long targetCapacity = recordingOffset + frameLength;
        if (targetCapacity > maxCatalogCapacity)
        {
            if (maxCatalogCapacity == oldCapacity)
            {
                throw new ArchiveException("catalog is full, max capacity reached: " + maxCatalogCapacity);
            }
            else
            {
                throw new ArchiveException(
                    "recording is too big: total recording length is " + frameLength + " bytes," +
                    " available space is " + (maxCatalogCapacity - recordingOffset) + " bytes");
            }
        }

        long newCapacity = oldCapacity;
        while (newCapacity < targetCapacity)
        {
            newCapacity = min(newCapacity + (newCapacity >> 1), maxCatalogCapacity);
        }

        final MappedByteBuffer mappedByteBuffer;
        try
        {
            unmapAndCloseChannel();
            catalogChannel = FileChannel.open(catalogFile.toPath(), READ, WRITE, SPARSE);
            mappedByteBuffer = catalogChannel.map(READ_WRITE, 0, newCapacity);
        }

View on GitHub (pinned to 6d60124e15)