aeron-io/aeron · error · IllegalArgumentException

media type is mandatory

Error message

media type is mandatory

What it means

ChannelUriStringBuilder.validate() enforces minimum required channel configuration. The media component is mandatory — without it no transport can be chosen — so a null media throws IllegalArgumentException before a URI can be built.

Solutions

  1. Call .media(ChannelUriStringBuilder.MEDIA_UDP) or MEDIA_IPC on the builder before validate()/build()
  2. Check the source config for a missing/misspelled media property and default it explicitly
  3. Always run validate() early (e.g. at startup) so missing media fails fast with a clear message

Example fix

// before
ChannelUriStringBuilder b = new ChannelUriStringBuilder().endpoint("localhost:40456");
b.validate(); // throws
// after
ChannelUriStringBuilder b = new ChannelUriStringBuilder()
    .media(CommonContext.UDP_MEDIA)
    .endpoint("localhost:40456");
b.validate();
Defensive patterns

Strategy: validation

Validate before calling

static ChannelUriStringBuilder requireMedia(ChannelUriStringBuilder b, String media) {
    if (media == null || media.isEmpty()) {
        throw new IllegalArgumentException("media is required for Aeron channel");
    }
    return b.media(media);
}

Type guard

static boolean hasMedia(ChannelUriStringBuilder b) {
    return b != null && b.validateQuietly(); // wrap validate() and return false on IAE
}

Try / catch

try {
    builder.validate().build();
} catch (IllegalArgumentException e) {
    if ("media type is mandatory".equals(e.getMessage())) {
        throw new IllegalArgumentException("Channel media missing in config; set 'udp' or 'ipc'", e);
    }
    throw e;
}

Prevention

When it happens

Trigger: Calling validate() (or build() after validate) on a ChannelUriStringBuilder where media() was never called, e.g. building a URI from a partially populated config object.

Common situations: Constructing a builder from config where the media key is missing/misspelled in a properties file; forgetting to call .media() on the fluent chain; conditional config branches that skip media assignment.

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

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

Appendix: source

Thrown at aeron-client/src/main/java/io/aeron/ChannelUriStringBuilder.java:216

        responseCorrelationId = null;
        maxResend = null;
        streamId = null;
        publicationWindowLength = null;

        return this;
    }

    /**
     * Validates that the collection of set parameters are valid together.
     *
     * @return this for a fluent API.
     * @throws IllegalArgumentException if the combination of params is invalid.
     */
    public ChannelUriStringBuilder validate()
    {
        if (null == media)
        {
            throw new IllegalArgumentException("media type is mandatory");
        }

        if (CommonContext.UDP_MEDIA.equals(media) && (null == endpoint && null == controlEndpoint))
        {
            throw new IllegalArgumentException("either 'endpoint' or 'control' must be specified for UDP.");
        }

        final boolean anyNonNull = null != initialTermId || null != termId || null != termOffset;
        final boolean anyNull = null == initialTermId || null == termId || null == termOffset;
        if (anyNonNull)
        {
            if (anyNull)
            {
                throw new IllegalArgumentException(
                    "either all or none of the parameters ['initialTermId', 'termId', 'termOffset'] must be provided");
            }

            if (termId - initialTermId < 0)

View on GitHub (pinned to 6d60124e15)