aeron-io/aeron · error · AeronException

Resolver Bootstrap Neighbor list too large. Can have a…

Error message

Resolver Bootstrap Neighbor list too large.  Can have a maximum of {MAX_BOOTSTRAP_NEIGHBORS}.

What it means

A configuration validation error at driver startup: the aeron.driver.resolver.bootstrap.neighbor property lists more comma-separated neighbors than the driver supports (MAX_BOOTSTRAP_NEIGHBORS). The NameResolver bootstrap neighbor list has a hard cap and the driver refuses to start rather than silently truncating it.

Solutions

1. Trim the neighbor list to at most MAX_BOOTSTRAP_NEIGHBORS entries (pick a representative subset of nodes).
2. Use 1-2 stable seed nodes and let the resolver learn the rest via gossip.
3. Check the Aeron docs/constant for the exact maximum for your version.
4. If more neighbors are genuinely required, upgrade Aeron to a version with a larger cap or file an issue.

Example fix

// before
-Daeron.driver.resolver.bootstrap.neighbor=node1:40456,node2:40456,node3:40456,node4:40456,... (too many)
// after
-Daeron.driver.resolver.bootstrap.neighbor=node1:40456,node2:40456

String[] neighbors = bootstrapNeighborCsv == null ? new String[0] : bootstrapNeighborCsv.split(",");
if (neighbors.length > MediaDriver.Context.MAX_BOOTSTRAP_NEIGHBORS) {
    throw new IllegalArgumentException("too many bootstrap neighbors: " + neighbors.length);
}

When it happens

Trigger: Setting the aeron.driver.resolver.bootstrap.neighbor system property / context value to a comma-separated list whose length exceeds MAX_BOOTSTRAP_NEIGHBORS, then launching MediaDriver (DriverNameResolver constructor).

Common situations: Enumerating every cluster node as a bootstrap neighbor in large clusters; copy-pasting a growing list over time; misunderstanding that only a couple of neighbors are needed to bootstrap.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Active media driver detected
• difference greater than 2^31 - 1: initialTermId=
• empty key not allowed at index
• failed to start clustered service(s)
• invalid cluster member id, must be an integer value

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

Appendix: source

Thrown at aeron-driver/src/main/java/io/aeron/driver/DriverNameResolver.java:142

        clock = ctx.cachedEpochClock();

        localDriverName = ctx.resolverName();
        localName = localDriverName.getBytes(StandardCharsets.US_ASCII);
        localSocketAddress = UdpNameResolutionTransport.getInterfaceAddress(ctx.resolverInterface());
        localAddress = localSocketAddress.getAddress().getAddress();

        neighborTimeoutMs = TimeUnit.NANOSECONDS.toMillis(ctx.resolverNeighborTimeoutNs());
        selfResolutionIntervalMs = TimeUnit.NANOSECONDS.toMillis(ctx.resolverSelfResolutionIntervalNs());
        neighborResolutionIntervalMs = TimeUnit.NANOSECONDS.toMillis(ctx.resolverNeighborResolutionIntervalNs());
        bootstrapNeighborResolutionIntervalMs = TimeUnit.NANOSECONDS.toMillis(
            ctx.resolverBootstrapNeighborResolutionIntervalNs());

        bootstrapNeighbors = null != ctx.resolverBootstrapNeighbor() ?
            ctx.resolverBootstrapNeighbor().split(",") : new String[0];

        if (MAX_BOOTSTRAP_NEIGHBORS < bootstrapNeighbors.length)
        {
            throw new AeronException(
                "Resolver Bootstrap Neighbor list too large.  Can have a maximum of " +
                MAX_BOOTSTRAP_NEIGHBORS + ".");
        }

        bootstrapNeighborAddresses = new InetSocketAddress[bootstrapNeighbors.length];
        bootstrapNeighborCounters = new AtomicCounter[bootstrapNeighbors.length];
        bootstrapNeighborConnected = new BitSet(bootstrapNeighborAddresses.length);

        final long nowMs = ctx.epochClock().time();
        bootstrapNeighborResolveDeadlineMs = nowMs + bootstrapNeighborResolutionIntervalMs;

        selfResolutionDeadlineMs = 0;
        neighborResolutionDeadlineMs = nowMs + neighborResolutionIntervalMs;

        cache = new DriverNameResolverCache(neighborTimeoutMs);

        final UdpChannel resolverChannel =
            UdpChannel.parse("aeron:udp?endpoint=" +

View on GitHub (pinned to 6d60124e15)