{"record":{"id":"37a25d34af68c434","repo":"aeron-io/aeron","slug":"clustermarkfile-headerlength-length-headerlengthcapacity","errorCode":null,"errorMessage":"ClusterMarkFile headerLength=<length> > headerLengthCapacity=<HEADER_LENGTH>","messagePattern":"ClusterMarkFile headerLength=<length> > headerLengthCapacity=<HEADER_LENGTH>","errorType":"exception","errorClass":"ClusterException","httpStatus":null,"severity":"error","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/service/ClusterMarkFile.java","lineNumber":562,"sourceCode":"        final String aeronDirectory,\n        final String controlChannel,\n        final String ingressChannel,\n        final String serviceName,\n        final String authenticator)\n    {\n        final int length =\n            HEADER_OFFSET +\n                MarkFileHeaderEncoder.BLOCK_LENGTH +\n                (5 * VarAsciiEncodingEncoder.lengthEncodingLength()) +\n                (null == aeronDirectory ? 0 : aeronDirectory.length()) +\n                (null == controlChannel ? 0 : controlChannel.length()) +\n                (null == ingressChannel ? 0 : ingressChannel.length()) +\n                (null == serviceName ? 0 : serviceName.length()) +\n                (null == authenticator ? 0 : authenticator.length());\n\n        if (length > HEADER_LENGTH)\n        {\n            throw new ClusterException(\n                \"ClusterMarkFile headerLength=\" + length + \" > headerLengthCapacity=\" + HEADER_LENGTH);\n        }\n    }\n\n    /**\n     * The filename to be used for the mark file given a service id.\n     *\n     * @param serviceId of the service the {@link ClusterMarkFile} represents.\n     * @return the filename to be used for the mark file given a service id.\n     */\n    public static String markFilenameForService(final int serviceId)\n    {\n        return SERVICE_FILENAME_PREFIX + serviceId + FILE_EXTENSION;\n    }\n\n    /**\n     * The filename to be used for the link file given a service id.\n     *","sourceCodeStart":544,"sourceCodeEnd":580,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/service/ClusterMarkFile.java#L544-L580","documentation":"ClusterMarkFile.checkHeaderLength computes the total encoded length of variable header fields (endpoints/channels, service name, authenticator) and throws ClusterException if it exceeds the fixed HEADER_LENGTH capacity of the mark file header. The header is a fixed-size region, so the combined string data must fit.","triggerScenarios":"Constructing a ClusterMarkFile with very long ingress/egress channel strings, a long service name, or a long authenticator class name whose combined length exceeds HEADER_LENGTH.","commonSituations":"Very long channel URIs with many query params, verbose fully-qualified authenticator class names, or several long fields concatenated in a containerized environment with long hostnames.","solutions":["Shorten the offending strings: trim channel URIs, use aliases, or a shorter service name/authenticator class name.","Check which field is longest (channel lengths dominate) and restructure the channel configuration.","If the header capacity is genuinely too small for your deployment, the field sizes are fixed by the format — restructure strings rather than expecting a larger header."],"exampleFix":"// before\nctx.serviceName(\"my-very-long-production-consensus-module-service-name\");\n// after\nctx.serviceName(\"consensus\"); // keep name + channels within header capacity","handlingStrategy":"validation","validationCode":"// java\nint len = (ingressChannel == null ? 0 : ingressChannel.length()) +\n          (serviceName == null ? 0 : serviceName.length()) +\n          (authenticator == null ? 0 : authenticator.length());\nif (len > ClusterMarkFile.HEADER_LENGTH) {\n    throw new IllegalStateException(\"mark file header strings too long: \" + len);\n}","typeGuard":null,"tryCatchPattern":"try {\n    ClusterMarkFile markFile = new ClusterMarkFile(...);\n} catch (ClusterException e) {\n    if (e.getMessage().contains(\"headerLength=\")) {\n        // shorten serviceName / channels and rebuild the configuration\n    }\n    throw e;\n}","preventionTips":["Keep service names short and channel URIs minimal.","Compute combined string lengths in your config validation suite before deploying.","Avoid embedding very long hostnames/endpoints in channel strings; use config aliases."],"tags":["java","mark-file","validation","size-limit"],"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"}