{"record":{"id":"f02e0060c9814e0f","repo":"aeron-io/aeron","slug":"invalid-catalog-capacity-provided-expected-value-min","errorCode":null,"errorMessage":"Invalid catalog capacity provided: expected value >= \" + MIN_CAPACITY + \", got \" + catalogCapacity","messagePattern":"Invalid catalog capacity provided: expected value >= \" \\+ MIN_CAPACITY \\+ \", got \" \\+ catalogCapacity","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/Catalog.java","lineNumber":931,"sourceCode":"            return checksum.compute(\n                catalogByteBufferAddress,\n                DESCRIPTOR_HEADER_LENGTH + recordingDescriptorOffset,\n                recordingLength);\n        }\n\n        return 0;\n    }\n\n    void catalogResized(final long oldCapacity, final long newCapacity)\n    {\n        ArchiveTracing.traceCatalogResize(oldCapacity, newCapacity);\n    }\n\n    private static void validateCapacity(final long catalogCapacity)\n    {\n        if (catalogCapacity < MIN_CAPACITY || catalogCapacity > MAX_CATALOG_LENGTH)\n        {\n            throw new IllegalArgumentException(\"Invalid catalog capacity provided: expected value >= \" +\n                MIN_CAPACITY + \", got \" + catalogCapacity);\n        }\n    }\n\n    private void initBuffers(final MappedByteBuffer catalogMappedByteBuffer)\n    {\n        catalogByteBuffer = catalogMappedByteBuffer;\n        catalogByteBuffer.order(BYTE_ORDER);\n        catalogBuffer = new UnsafeBuffer(catalogByteBuffer);\n        catalogByteBufferAddress = catalogBuffer.addressOffset();\n        fieldAccessBuffer = new UnsafeBuffer(catalogByteBuffer);\n        headerAccessBuffer = new UnsafeBuffer(catalogByteBuffer);\n    }\n\n    private void buildIndex(final boolean writable)\n    {\n        final int endOffset = (int)capacity;\n        int offset = firstRecordingDescriptorOffset;","sourceCodeStart":913,"sourceCodeEnd":949,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/Catalog.java#L913-L949","documentation":"Thrown by Catalog.validateCapacity when the requested catalog file capacity is outside the allowed range: below MIN_CAPACITY or above MAX_CATALOG_LENGTH. The catalog file must be large enough for its page-size header/entries yet addressable within the catalog's internal offset limits. This is an IllegalArgumentException raised during archive catalog construction, so it fails fast at startup.","triggerScenarios":"Calling CatalogTool or Archive.Context with a catalog capacity < MIN_CAPACITY (e.g. 0 or negative, or an unparseable CLI arg defaulting to 0) or greater than MAX_CATALOG_LENGTH when constructing a Catalog or configuring archiveCatalogCapacity().","commonSituations":"Typo'd CLI flag (e.g. --max-catalog-capacity 0); computing capacity from an unset config value that resolves to 0; copy-pasting a capacity in the wrong unit (KB vs bytes) yielding a huge number; passing bytes-per-recording instead of total catalog size.","solutions":["Set the catalog capacity to at least MIN_CAPACITY (a few KB) and at most MAX_CATALOG_LENGTH as defined in Catalog.java","Check where the value comes from (CLI flag, system property, config) and ensure a valid numeric value is supplied","Use Archive.Configuration.MAX_CATALOG_CAPACITY default or omit the setting to let Aeron pick a valid default","Validate the value in your own config loader before passing it to Archive.Context.maxCatalogCapacity"],"exampleFix":"// before\ncontext.maxCatalogCapacity(Long.parseLong(System.getProperty(\"aeron.archive.catalog.capacity\", \"0\")));\n// after\nlong capacity = Long.parseLong(System.getProperty(\"aeron.archive.catalog.capacity\",\n    String.valueOf(Archive.Configuration.MAX_CATALOG_CAPACITY_DEFAULT)));\ncontext.maxCatalogCapacity(Math.max(Catalog.MIN_CAPACITY, capacity));","handlingStrategy":"validation","validationCode":"long capacity = configuredCatalogCapacity;\nif (capacity < Catalog.MIN_CAPACITY || capacity > Catalog.MAX_CATALOG_LENGTH) {\n    throw new IllegalArgumentException(\"catalog capacity \" + capacity +\n        \" outside valid range [\" + Catalog.MIN_CAPACITY + \", \" + Catalog.MAX_CATALOG_LENGTH + \"]\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    context.maxCatalogCapacity(parseCapacity(config));\n} catch (IllegalArgumentException e) {\n    log.warn(\"Invalid catalog capacity, falling back to default\", e);\n    context.maxCatalogCapacity(Archive.Configuration.MAX_CATALOG_CAPACITY_DEFAULT);\n}","preventionTips":["Validate numeric CLI/config values before passing them to Archive.Context","Never pass unvalidated Long.parseLong results (0/negative on failure) as capacities","Check units (bytes not KB/MB) when computing capacity","Use the library defaults unless you have a specific capacity requirement"],"tags":["aeron-archive","configuration","argument-validation"],"backgroundTag":"invalid-config-value","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"}