aeron-io/aeron · error · InvalidChannelException

Media timestamps 'media-rcv-timestamp-offset' are not…

Error message

Media timestamps 'media-rcv-timestamp-offset' are not supported in the Java driver: channel={channel}

What it means

The channel URI contains the media-rcv-timestamp-offset parameter, which requests kernel/software receive timestamps for media traffic. This feature is only implemented in the C driver; the Java driver explicitly rejects it with InvalidChannelException at channel validation time.

Solutions

1. Remove media-rcv-timestamp-offset from the channel URI when using the Java driver.
2. Switch to the Aeron C driver if media receive timestamps are required.
3. Use the supported publication-rcv-timestamp-offset / channel-rcv-timestamp-offset parameters if that satisfies the timestamping need, subject to experimental-features being enabled.
4. Guard the URI assembly with a check of the driver implementation before adding timestamp params.

Example fix

// before
String uri = "aeron:udp?endpoint=localhost:40456|media-rcv-timestamp-offset=48";
aeron.addPublication(uri, 1001);
// after
String uri = "aeron:udp?endpoint=localhost:40456";
aeron.addPublication(uri, 1001);

if (ChannelUri.parse(channel).containsKey("media-rcv-timestamp-offset")) throw new IllegalArgumentException("media-rcv-timestamp-offset unsupported in Java driver");

boolean isJavaDriverCompatible(ChannelUri uri) {
  return !uri.containsKey("media-rcv-timestamp-offset");
}

try { aeron.addSubscription(uri, streamId); }
catch (InvalidChannelException e) { if (e.getMessage().contains("media-rcv-timestamp-offset")) { /* strip param or switch to C driver */ } else throw e; }

When it happens

Trigger: Calling Aeron.addSubscription()/addPublication() or adding a destination with a URI containing media-rcv-timestamp-offset (e.g. "aeron:udp?media-rcv-timestamp-offset=48").

Common situations: Porting a configuration written for the C/C++ driver to the Java driver; enabling hardware/network timestamping features documented for Aeron C; sharing a shared config file between Java and C drivers.

Related errors

• Aeron URIs must start with 'aeron:', found
• channelReceiveTimestampOffset must be a number or the value
• channelSendTimestampOffset must be a number or the value
• destinations must not contain the key
• difference greater than 2^31 - 1: termId=

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

Appendix: source

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

                    udpChannel.originalUriString());
        }
    }

    private static void validateControlForSubscription(final UdpChannel udpChannel)
    {
        if (udpChannel.hasExplicitControl() &&
            0 == udpChannel.localControl().getPort())
        {
            throw new IllegalArgumentException(MDC_CONTROL_PARAM_NAME + " has port=0 for subscription: channel=" +
                udpChannel.originalUriString());
        }
    }

    private static void validateTimestampConfiguration(final UdpChannel udpChannel)
    {
        if (null != udpChannel.channelUri().get(MEDIA_RCV_TIMESTAMP_OFFSET_PARAM_NAME))
        {
            throw new InvalidChannelException(
                "Media timestamps '" + MEDIA_RCV_TIMESTAMP_OFFSET_PARAM_NAME +
                    "' are not supported in the Java driver: channel=" + udpChannel.originalUriString());
        }
    }

    private static void validateDestinationUri(final ChannelUri uri, final String destinationUri)
    {
        if (SPY_QUALIFIER.equals(uri.prefix()))
        {
            throw new InvalidChannelException("Aeron spies are invalid as send destinations: channel=" +
                destinationUri);
        }

        for (final String invalidKey : INVALID_DESTINATION_KEYS)
        {
            if (uri.containsKey(invalidKey))
            {
                throw new InvalidChannelException(

View on GitHub (pinned to 6d60124e15)