aeron-io/aeron · error · ConfigurationException

Unable to derive…

Error message

Unable to derive Archive.Context.archiveClientContext.controlResponseChannel as Archive.Context.controlChannel.endpoint=${endpoint} and is not in the <host>:<port> format

What it means

When the archive must derive an internal archive client's control-response channel from the control channel URI, it parses the endpoint and replaces the port with 0. If the control channel has no endpoint parameter or the endpoint lacks a '<host>:<port>' form (no ':' present), Archive throws ConfigurationException because the response channel cannot be derived.

Solutions

1. Ensure the control channel URI includes an explicit endpoint in <host>:<port> format, e.g. 'aeron:udp?endpoint=host:8010'.
2. Explicitly set archiveClientContext.controlResponseChannel(...) so derivation is unnecessary.
3. Parse the intended URI with ChannelUri to confirm the endpoint parameter is present before launching.

Example fix

// before
ctx.controlChannel("aeron:udp?interface=eth0:8010");
// after
ctx.controlChannel("aeron:udp?endpoint=192.168.1.10:8010");

ChannelUri uri = ChannelUri.parse(controlChannel);
String endpoint = uri.get("endpoint");
if (endpoint == null || endpoint.lastIndexOf(':') < 0)
{
    throw new IllegalArgumentException("control channel endpoint must be <host>:<port>");
}

When it happens

Trigger: Configuring Archive.Context.controlChannel with a URI lacking an endpoint param (e.g. using an interface name or wildcard-only form) while archiveClientContext.controlResponseChannel is unset, forcing derivation from the control channel.

Common situations: Using 'aeron:udp?interface=0.0.0.0:8010' style control channels or accidentally omitting endpoint=; multi-host setups where the control channel was copied from driver config.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

• Aeron client instance must set…
• Aeron client must use a RethrowingErrorHandler
• segment file length not a power of 2
• segment file length not in valid range
• Archive.Context.archiveClientContext.controlResponseChannel…

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

Appendix: source

Thrown at aeron-archive/src/main/java/io/aeron/archive/Archive.java:1529

                    null != recordChecksum ? recordChecksumBuffer() : dataBuffer());
            }

            if (null == archiveClientContext)
            {
                archiveClientContext = new AeronArchive.Context();
            }

            if (null == archiveClientContext.controlResponseChannel())
            {
                if (controlChannelEnabled)
                {
                    final ChannelUri controlChannelUri = ChannelUri.parse(controlChannel);
                    final String endpoint = controlChannelUri.get(ENDPOINT_PARAM_NAME);
                    final int separatorIndex;

                    if (null == endpoint || -1 == (separatorIndex = endpoint.lastIndexOf(':')))
                    {
                        throw new ConfigurationException(
                            "Unable to derive Archive.Context.archiveClientContext.controlResponseChannel as " +
                                "Archive.Context.controlChannel.endpoint=" + endpoint +
                                " and is not in the <host>:<port> format");
                    }

                    final String responseEndpoint = endpoint.substring(0, separatorIndex) + ":0";
                    final String responseChannel = new ChannelUriStringBuilder()
                        .media("udp")
                        .endpoint(responseEndpoint)
                        .build();

                    archiveClientContext.controlResponseChannel(responseChannel);
                }
                else
                {
                    throw new ConfigurationException(
                        "Archive.Context.archiveClientContext.controlResponseChannel must be set if " +
                            "Archive.Context.controlChannelEnabled is false"

View on GitHub (pinned to 6d60124e15)