aeron-io/aeron · error · ConfigurationException

`resolverName` is required when `resolverInterface` is set

Error message

`resolverName` is required when `resolverInterface` is set

What it means

The driver MediaDriver.Context requires that when a resolverInterface is configured, a resolverName is also provided. The name is what the name resolver advertises over the resolver interface, so an interface without a name is an incomplete configuration.

Solutions

1. Add a unique resolverName to the driver context
2. Remove the resolverInterface setting if the name resolver is not actually used
3. Set the aeron.dir.resolver.name system property alongside aeron.dir.resolver.interface

Example fix

// before
ctx.resolverInterface("0.0.0.0:40456");
// after
ctx.resolverInterface("0.0.0.0:40456").resolverName("driver-a");

if (resolverInterface != null && (resolverName == null || resolverName.isEmpty())) throw new IllegalArgumentException("resolverName required with resolverInterface");

try { mediaDriver = MediaDriver.launch(ctx); } catch (ConfigurationException e) { log.error("driver config incomplete: {}", e.getMessage()); }

When it happens

Trigger: Building a MediaDriver.Context with .resolverInterface("...") but leaving resolverName null or empty, then calling conclude()/start().

Common situations: Copy-pasting multi-driver or name-resolver sample configs and filling in only the interface; setting the interface via system property but not the name; switching from the default driver to a name-resolver topology.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• Aeron client instance must set…
• Aeron client must use a RethrowingErrorHandler
• Aeron client must use a RethrowingErrorHandler
• AeronArchive.Context.controlRequestChannel must be set
• AeronArchive.Context.controlResponseChannel must be set

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

Appendix: source

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

            if (null == nameResolver)
            {
                nameResolver = DefaultNameResolver.INSTANCE;
            }

            if (null == channelReceiveTimestampClock)
            {
                channelReceiveTimestampClock = new SystemEpochNanoClock();
            }

            if (null == channelSendTimestampClock)
            {
                channelSendTimestampClock = new SystemEpochNanoClock();
            }

            if (null != resolverInterface && Strings.isEmpty(resolverName))
            {
                throw new ConfigurationException("`resolverName` is required when `resolverInterface` is set");
            }
        }

        private void concludeCounters()
        {
            if (null == countersManager)
            {
                if (countersMetaDataBuffer() == null)
                {
                    countersMetaDataBuffer(createCountersMetaDataBuffer(cncByteBuffer, cncMetaDataBuffer));
                }

                if (countersValuesBuffer() == null)
                {
                    countersValuesBuffer(createCountersValuesBuffer(cncByteBuffer, cncMetaDataBuffer));
                }

                final long reuseTimeoutMs = counterFreeToReuseTimeoutNs > 0 ?

View on GitHub (pinned to 6d60124e15)