aeron-io/aeron · critical · ArchiveException

catalog is full, max capacity reached: " +…

Error message

catalog is full, max capacity reached: " + maxCatalogCapacity

What it means

When appending a new recording descriptor, Catalog computes the target capacity (nextRecordingDescriptorOffset + frameLength). If it exceeds maxCatalogCapacity and the file is already at its maximum capacity (maxCatalogCapacity == oldCapacity, i.e. it cannot be grown further), this ArchiveException is thrown: the catalog file has no room for another recording descriptor.

Solutions

Increase the archive's maxCatalogSize configuration so the catalog file can grow.
Purge/truncate old recordings from the catalog with ArchiveTool to free descriptor slots.
Move to a larger volume and expand the catalog, then restart the archive.

Example fix

// before (default catalog cap too small)
Archive.Context ctx = new Archive.Context().archiveDir(archiveDir);
// after: allow a larger catalog file
Archive.Context ctx = new Archive.Context()
    .archiveDir(archiveDir)
    .maxCatalogSize(2L * 1024L * 1024L * 1024L); // 2 GiB

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-check catalog usage
long catalogSizeBytes = new File(archiveDir, Catalog.CATALOG_FILE_NAME).length();
if (catalogSizeBytes >= configuredMaxCatalogSize * 0.95) {
    // alert / purge old recordings / grow maxCatalogSize before recording again
}

Try / catch

try {
    catalog.addNewRecording(...);
} catch (ArchiveException e) {
    if (e.getMessage().startsWith("catalog is full")) {
        // grow maxCatalogSize and restart, or purge old descriptors, then retry
    } else { throw e; }
}

Prevention

Set maxCatalogSize generously for expected recording counts (each descriptor has fixed overhead).
Monitor catalog file size and alert before it approaches capacity.
Regularly truncate/purge recordings that are no longer needed.

When it happens

Trigger: Starting a new recording (Catalog.addNewRecording / descriptor add path) when the catalog file has reached its configured maximum size and cannot be extended any further.

Common situations: Long-lived archives that accumulated more recordings than the default catalog capacity supports; archives configured with a small maxCatalogSize; never trimming old recordings so the catalog fills over months of operation.

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/90a4aeb3c14a9146. Report an issue: GitHub.

Appendix: source

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

    {
        final long recordingDescriptorOffset = catalogIndex.recordingOffset(recordingId);
        if (CatalogIndex.NULL_VALUE == recordingDescriptorOffset)
        {
            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
        {

View on GitHub (pinned to 6d60124e15)