{"record":{"id":"b98933807b0e8389","repo":"aeron-io/aeron","slug":"archivemarkfile-headerlength-headerlength","errorCode":null,"errorMessage":"ArchiveMarkFile headerLength=${headerLength} > headerLengthCapacity=${HEADER_LENGTH}","messagePattern":"ArchiveMarkFile headerLength=(.+?) > headerLengthCapacity=(.+?)","errorType":"exception","errorClass":"ArchiveException","httpStatus":null,"severity":"error","filePath":"aeron-archive/src/main/java/io/aeron/archive/ArchiveMarkFile.java","lineNumber":464,"sourceCode":"        {\n            markFile.mappedByteBuffer().force();\n        }\n    }\n\n    private static int alignedTotalFileLength(final Archive.Context ctx)\n    {\n        final int headerLength =\n            HEADER_OFFSET +\n            MarkFileHeaderEncoder.BLOCK_LENGTH +\n            (4 * VarAsciiEncodingEncoder.lengthEncodingLength()) +\n            (null != ctx.controlChannel() ? ctx.controlChannel().length() : 0) +\n            ctx.localControlChannel().length() +\n            (null != ctx.recordingEventsChannel() ? ctx.recordingEventsChannel().length() : 0) +\n            ctx.aeronDirectoryName().length();\n\n        if (headerLength > HEADER_LENGTH)\n        {\n            throw new ArchiveException(\n                \"ArchiveMarkFile headerLength=\" + headerLength + \" > headerLengthCapacity=\" + HEADER_LENGTH);\n        }\n\n        final int filePageSize = null != ctx.aeron() ? ctx.aeron().context().filePageSize() :\n            CommonContext.driverFilePageSize(\n                new File(ctx.aeronDirectoryName()), ctx.epochClock(), new CommonContext().driverTimeoutMs());\n\n        LogBufferDescriptor.checkPageSize(filePageSize);\n\n        return BitUtil.align(HEADER_LENGTH + ctx.errorBufferLength(), filePageSize);\n    }\n\n    String aeronDirectory()\n    {\n        headerDecoder.sbeRewind();\n        headerDecoder.skipControlChannel();\n        headerDecoder.skipLocalControlChannel();\n        headerDecoder.skipEventsChannel();","sourceCodeStart":446,"sourceCodeEnd":482,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-archive/src/main/java/io/aeron/archive/ArchiveMarkFile.java#L446-L482","documentation":"Thrown by ArchiveMarkFile during alignedTotalFileLength when the computed header length (derived from configured control channel/endpoint strings, recording events channel, and aeron directory name lengths) exceeds the fixed HEADER_LENGTH capacity of the mark file header. The archive refuses to start because it cannot persist its identity metadata in the fixed-size header.","triggerScenarios":"Starting an Archive with ArchiveMarkFileHeaderLength exceeding capacity, typically because the aeronDirectoryName or localControlChannel/recordingEventsChannel strings are very long (long paths, long hostnames/ports in endpoint URIs).","commonSituations":"Running in environments with deep/long temp directories (containers, CI) making aeronDirectoryName too long; very long control channel endpoint URIs with DNS names or IPv6 addresses; archive mark file version mismatch across configurations.","solutions":["Shorten the aeronDirectoryName (move the mark file/driver directory closer to the filesystem root).","Shorten the archive's localControlChannel and recordingEventsChannel URIs (use IP addresses instead of long hostnames, drop unneeded parameters).","Set aeron.archive.mark.file.header.length to a larger value if your build exposes the context override for it.","Check for stale/oversized mark file config and clean the old archive directory if safe."],"exampleFix":"// before\nArchive.Context ctx = new Archive.Context()\n    .aeronDirectoryName(\"/very/long/path/to/aeron/subsystem/dir/with/many/components\")\n    .localControlChannel(\"aeron:udp?endpoint=archive-control.very.long.internal.domain.example.com:8010\");\n// after\nArchive.Context ctx = new Archive.Context()\n    .aeronDirectoryName(\"/tmp/aeron\")\n    .localControlChannel(\"aeron:udp?endpoint=127.0.0.1:8010\");","handlingStrategy":"validation","validationCode":"String aeronDir = ctx.aeronDirectoryName();\nString headerSources = ctx.localControlChannel().length() +\n    (ctx.recordingEventsChannel() != null ? ctx.recordingEventsChannel().length() : 0) +\n    aeronDir.length();\nif (headerSources > 65536 /* expected safe budget; actual cap is ArchiveMarkFile.HEADER_LENGTH */) {\n    throw new IllegalStateException(\"Archive mark file header inputs too long: \" + headerSources);\n}","typeGuard":null,"tryCatchPattern":"try {\n    archive = Archive.launch(ctx);\n} catch (ArchiveException e) {\n    if (e.getMessage().contains(\"headerLength=\") && e.getMessage().contains(\"headerLengthCapacity=\")) {\n        // shorten aeronDirectoryName / channel URIs and relaunch\n        ctx.aeronDirectoryName(Files.createTempDirectory(\"aeron\").toString());\n        archive = Archive.launch(ctx);\n    } else {\n        throw e;\n    }\n}","preventionTips":["Keep aeronDirectoryName short; avoid deeply nested temp paths in containers and CI.","Use concise endpoint URIs (IPs, no long DNS suffixes) for localControlChannel and recordingEventsChannel.","Pin a common archive version/config across nodes so header layout expectations stay consistent."],"tags":["aeron-archive","mark-file","header-capacity"],"backgroundTag":"value-out-of-range","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"}