aeron-io/aeron · error · IllegalArgumentException

control-mode=response was specified, but no…

Error message

control-mode=response was specified, but no response-correlation-id set

What it means

A channel URI specified control-mode=response but omitted the mandatory response-correlation-id parameter, which identifies the image/subscription the response publication should correlate with. The driver throws IllegalArgumentException during URI parameter parsing.

Solutions

1. Add response-correlation-id=<correlationId> to the channel URI (value obtained from the requested image's correlation id).
2. When using ChannelUriStringBuilder, call .responseCorrelationId(id) together with controlMode(Response).
3. Store the correlation id delivered with the response-setup event before constructing the response channel.
4. Validate response URIs (control-mode=response implies response-correlation-id present) before passing to the driver.

Example fix

// before
String uri = "aeron:udp?endpoint=h:40456|control-mode=response";
// after
String uri = "aeron:udp?endpoint=h:40456|control-mode=response|response-correlation-id=" + imageCorrelationId;

ChannelUri uri = ChannelUri.parse(channel);
if ("response".equals(uri.get("control-mode")) && uri.get("response-correlation-id") == null)
  throw new IllegalArgumentException("control-mode=response requires response-correlation-id");

boolean responseChannelIsComplete(ChannelUri uri) {
  return !"response".equals(uri.get("control-mode")) || uri.get("response-correlation-id") != null;
}

try { aeron.addPublication(uri, streamId); }
catch (IllegalArgumentException e) { if (e.getMessage().contains("no response-correlation-id")) { /* append response-correlation-id */ } else throw e; }

When it happens

Trigger: Creating a publication/subscription with a URI like "aeron:udp?control-mode=response" without "response-correlation-id=<value>"; setting control-mode via ChannelUriStringBuilder without calling responseCorrelationId().

Common situations: Implementing the response channel (RPC-style) pattern and forgetting the correlation id returned in the Image/connection event; build scripts that only set control-mode; partial porting of C examples to Java.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• image.correlationId=
• Aeron spies are invalid as send destinations: channel=
• AeronArchive.Context.messageRetryAttempts must be > 0, got:
• applicationSpecificFeedback length must be equal to
• clientLivenessTimeoutNs=

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

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/DriverConductor.java:2768

            if (null != responsePublicationImage)
            {
                responsePublicationImage.responseSessionId(publication.sessionId());
                responsePublicationImage.requestNextSmDeadlineReset();
            }

            state = State.DONE;
        }

        private PublicationImage findResponsePublicationImage()
        {
            if (!params.isResponse)
            {
                return null;
            }

            if (NULL_VALUE == params.responseCorrelationId)
            {
                throw new IllegalArgumentException(
                    "control-mode=response was specified, but no response-correlation-id set");
            }

            if (PROTOTYPE_VALUE_CORRELATION_ID == params.responseCorrelationId)
            {
                return null;
            }

            for (final PublicationImage publicationImage : publicationImages)
            {
                if (publicationImage.correlationId() == params.responseCorrelationId)
                {
                    if (publicationImage.hasSendResponseSetup())
                    {
                        return publicationImage;
                    }
                    else
                    {

View on GitHub (pinned to 6d60124e15)