{"record":{"id":"2c29aef51b7d5927","repo":"aeron-io/aeron","slug":"recording-is-too-big-total-recording-length-is-framelength","errorCode":null,"errorMessage":"recording is too big: total recording length is \" + frameLength + \" bytes,\" + \" available space is \" + (maxCatalogCapacity - recordingOffset) + \" bytes","messagePattern":"recording is too big: total recording length is \" \\+ frameLength \\+ \" bytes,\" \\+ \" available space is \" \\+ \\(maxCatalogCapacity - recordingOffset\\) \\+ \" bytes","errorType":"exception","errorClass":"ArchiveException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/Catalog.java","lineNumber":856,"sourceCode":"            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        {\n            unmapAndCloseChannel();\n            catalogChannel = FileChannel.open(catalogFile.toPath(), READ, WRITE, SPARSE);\n            mappedByteBuffer = catalogChannel.map(READ_WRITE, 0, newCapacity);\n        }","sourceCodeStart":838,"sourceCodeEnd":874,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/Catalog.java#L838-L874","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nArchive.Context ctx = new Archive.Context(); // default max catalog capacity\n// after\nArchive.Context ctx = new Archive.Context()\n    .maxCatalogCapacity(1024L * 1024L * 1024L * 8L); // 8GB catalog","handlingStrategy":"validation","validationCode":"// Before configuring the archive, estimate entries and set capacity accordingly.\nlong expectedRecordings = 100_000;\nlong minCapacity = expectedRecordings * 512; // conservative bytes per catalog entry\nlong maxCapacity = new Archive.Context().maxCatalogCapacity();\nif (maxCapacity - 1024 < minCapacity) {\n    throw new IllegalStateException(\"catalog capacity \" + maxCapacity +\n        \" too small for \" + expectedRecordings + \" recordings\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    archive.start();\n} catch (ArchiveException e) {\n    if (e.getMessage().contains(\"catalog is full\") || e.getMessage().contains(\"recording is too big\")) {\n        // alert ops to grow/migrate the catalog, then reconfigure with larger maxCatalogCapacity\n    } else {\n        throw e;\n    }\n}","preventionTips":["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"],"tags":["aeron-archive","storage-capacity","catalog-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"}