{"record":{"id":"90a4aeb3c14a9146","repo":"aeron-io/aeron","slug":"catalog-is-full-max-capacity-reached-maxcatalogcapacity","errorCode":null,"errorMessage":"catalog is full, max capacity reached: \" + maxCatalogCapacity","messagePattern":"catalog is full, max capacity reached: \" \\+ maxCatalogCapacity","errorType":"exception","errorClass":"ArchiveException","httpStatus":null,"severity":"critical","filePath":"aeron-archive/src/main/java/io/aeron/archive/Catalog.java","lineNumber":852,"sourceCode":"    {\n        final long recordingDescriptorOffset = catalogIndex.recordingOffset(recordingId);\n        if (CatalogIndex.NULL_VALUE == recordingDescriptorOffset)\n        {\n            return -1;\n        }\n        return (int)recordingDescriptorOffset;\n    }\n\n    void growCatalog(final long maxCatalogCapacity, final int frameLength)\n    {\n        final long oldCapacity = capacity;\n        final long recordingOffset = nextRecordingDescriptorOffset;\n        final long targetCapacity = recordingOffset + frameLength;\n        if (targetCapacity > maxCatalogCapacity)\n        {\n            if (maxCatalogCapacity == oldCapacity)\n            {\n                throw new ArchiveException(\"catalog is full, max capacity reached: \" + maxCatalogCapacity);\n            }\n            else\n            {\n                throw new ArchiveException(\n                    \"recording is too big: total recording length is \" + frameLength + \" bytes,\" +\n                    \" available space is \" + (maxCatalogCapacity - recordingOffset) + \" bytes\");\n            }\n        }\n\n        long newCapacity = oldCapacity;\n        while (newCapacity < targetCapacity)\n        {\n            newCapacity = min(newCapacity + (newCapacity >> 1), maxCatalogCapacity);\n        }\n\n        final MappedByteBuffer mappedByteBuffer;\n        try\n        {","sourceCodeStart":834,"sourceCodeEnd":870,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/Catalog.java#L834-L870","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before (default catalog cap too small)\nArchive.Context ctx = new Archive.Context().archiveDir(archiveDir);\n// after: allow a larger catalog file\nArchive.Context ctx = new Archive.Context()\n    .archiveDir(archiveDir)\n    .maxCatalogSize(2L * 1024L * 1024L * 1024L); // 2 GiB","handlingStrategy":"try-catch","validationCode":"// Pre-check catalog usage\nlong catalogSizeBytes = new File(archiveDir, Catalog.CATALOG_FILE_NAME).length();\nif (catalogSizeBytes >= configuredMaxCatalogSize * 0.95) {\n    // alert / purge old recordings / grow maxCatalogSize before recording again\n}","typeGuard":null,"tryCatchPattern":"try {\n    catalog.addNewRecording(...);\n} catch (ArchiveException e) {\n    if (e.getMessage().startsWith(\"catalog is full\")) {\n        // grow maxCatalogSize and restart, or purge old descriptors, then retry\n    } else { throw e; }\n}","preventionTips":["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."],"tags":["aeron-archive","catalog","capacity","disk-full"],"backgroundTag":"file-size-limit-exceeded","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"}