aeron-io/aeron · error · ClusterException

ClusterMarkFile headerLength=

Error message

ClusterMarkFile headerLength=<length> > headerLengthCapacity=<HEADER_LENGTH>

What it means

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.

Solutions

1. Shorten the offending strings: trim channel URIs, use aliases, or a shorter service name/authenticator class name.
2. Check which field is longest (channel lengths dominate) and restructure the channel configuration.
3. 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.

Example fix

// before
ctx.serviceName("my-very-long-production-consensus-module-service-name");
// after
ctx.serviceName("consensus"); // keep name + channels within header capacity

// java
int len = (ingressChannel == null ? 0 : ingressChannel.length()) +
          (serviceName == null ? 0 : serviceName.length()) +
          (authenticator == null ? 0 : authenticator.length());
if (len > ClusterMarkFile.HEADER_LENGTH) {
    throw new IllegalStateException("mark file header strings too long: " + len);
}

try {
    ClusterMarkFile markFile = new ClusterMarkFile(...);
} catch (ClusterException e) {
    if (e.getMessage().contains("headerLength=")) {
        // shorten serviceName / channels and rebuild the configuration
    }
    throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• name + " cannot be negative: value=" + value
• Invalid errorBufferLength
• mark file major version <SemanticVersion.major(version)>…
• existing Mark file type
• gapLength must be smaller than gapRadix

AI-assisted analysis of aeron-io/aeron@6d60124e15 (2026-09-12). Data as JSON: /api/errors/37a25d34af68c434. Report an issue: GitHub.

Appendix: source

Thrown at aeron-cluster/src/main/java/io/aeron/cluster/service/ClusterMarkFile.java:562

        final String aeronDirectory,
        final String controlChannel,
        final String ingressChannel,
        final String serviceName,
        final String authenticator)
    {
        final int length =
            HEADER_OFFSET +
                MarkFileHeaderEncoder.BLOCK_LENGTH +
                (5 * VarAsciiEncodingEncoder.lengthEncodingLength()) +
                (null == aeronDirectory ? 0 : aeronDirectory.length()) +
                (null == controlChannel ? 0 : controlChannel.length()) +
                (null == ingressChannel ? 0 : ingressChannel.length()) +
                (null == serviceName ? 0 : serviceName.length()) +
                (null == authenticator ? 0 : authenticator.length());

        if (length > HEADER_LENGTH)
        {
            throw new ClusterException(
                "ClusterMarkFile headerLength=" + length + " > headerLengthCapacity=" + HEADER_LENGTH);
        }
    }

    /**
     * The filename to be used for the mark file given a service id.
     *
     * @param serviceId of the service the {@link ClusterMarkFile} represents.
     * @return the filename to be used for the mark file given a service id.
     */
    public static String markFilenameForService(final int serviceId)
    {
        return SERVICE_FILENAME_PREFIX + serviceId + FILE_EXTENSION;
    }

    /**
     * The filename to be used for the link file given a service id.
     *

View on GitHub (pinned to 6d60124e15)