aeron-io/aeron · error · IllegalArgumentException

applicationSpecificFeedback length must be equal to

Error message

applicationSpecificFeedback length must be equal to {SIZE_OF_LONG} bytes: length={length}

What it means

Aeron throws this when an applicationSpecificFeedback value used to derive a receiver group tag is not exactly 8 bytes (the size of a long). The ASFB bytes are interpreted as a little-endian long to form the receiverGroupTag, so any other length is rejected at Context.conclude().

Solutions

1. Pad or truncate your ASFB payload to exactly 8 bytes before setting it
2. Set Context.receiverGroupTag(long) instead and let Aeron encode the bytes
3. Use ByteBuffers.longToBytes / manual little-endian encoding to build the 8-byte array

Example fix

// before
context.applicationSpecificFeedback("mytag".getBytes());
// after
byte[] asfb = new byte[SIZE_OF_LONG];
ByteBuffers.putLongL(asfb, 0, 0x6d79746167L);
context.applicationSpecificFeedback(asfb);

if (asfb != null && asfb.length != 0 && asfb.length != 8) throw new IllegalArgumentException("applicationSpecificFeedback must be 8 bytes");

boolean isValidAsfb(byte[] b) { return b == null || b.length == 0 || b.length == Long.BYTES; }

try { ctx.applicationSpecificFeedback(asfb); ctx.conclude(); } catch (IllegalArgumentException e) { log.error("bad ASFB length", e); }

When it happens

Trigger: Calling Context.applicationSpecificFeedback(byte[]) (or the corresponding builder method) with a non-empty array whose length != 8 while no explicit receiverGroupTag is set.

Common situations: Hand-crafting ASFB bytes from a string or UUID without padding/truncating to exactly 8 bytes; copying tag bytes from another protocol with different widths; passing a human-readable tag string like 'my-tag' (6 bytes).

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• AeronArchive.Context.messageRetryAttempts must be > 0, got:
• clientLivenessTimeoutNs=
• control has port=0 for subscription: channel=
• difference greater than 2^31 - 1: termId=
• filePageSize not a power of 2

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

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/MediaDriver.java:4393

            }

            if (null == receiveChannelEndpointSupplier)
            {
                receiveChannelEndpointSupplier = Configuration.receiveChannelEndpointSupplier();
            }

            if (null == applicationSpecificFeedback)
            {
                applicationSpecificFeedback = Configuration.applicationSpecificFeedback();
            }

            if (null == receiverGroupTag)
            {
                if (applicationSpecificFeedback.length > 0)
                {
                    if (applicationSpecificFeedback.length != SIZE_OF_LONG)
                    {
                        throw new IllegalArgumentException(
                            "applicationSpecificFeedback length must be equal to " + SIZE_OF_LONG +
                            " bytes: length=" + applicationSpecificFeedback.length);
                    }

                    final UnsafeBuffer buffer = new UnsafeBuffer(applicationSpecificFeedback);
                    receiverGroupTag = buffer.getLong(0, ByteOrder.LITTLE_ENDIAN);
                }
            }

            if (null == receiveChannelEndpointThreadLocals)
            {
                receiveChannelEndpointThreadLocals = new ReceiveChannelEndpointThreadLocals();
            }

            if (null == congestionControlSupplier)
            {
                congestionControlSupplier = Configuration.congestionControlSupplier();
            }

View on GitHub (pinned to 6d60124e15)