What causes "Invalid idle sleep duration: ns" in aeron-io/aeron?

Set idleSleepDurationNs to a value between 0 and 1_000_000_000 nanoseconds

aeron-io/aeron · error · ConfigurationException

Invalid idle sleep duration

Error message

Invalid idle sleep duration: <idleSleepDurationNs>ns

What it means

Aeron.Context throws this ConfigurationException when idleSleepDurationNs is negative or greater than 1 second. This value configures the SleepingMillisIdleStrategy used by the client conductor when no work is available, so it must be a sane sleep duration within [0, 1s].

Solutions

Set idleSleepDurationNs to a value between 0 and 1_000_000_000 nanoseconds
Clamp or validate the value read from configuration before passing it to the Context
Use a different IdleStrategy via ctx.idleStrategy(...) if sub-millisecond or longer sleeps are needed

Example fix

// before
ctx.idleSleepDurationNs(Long.parseLong(props.getProperty("idle.ns"))); // e.g. 10000000000 -> throws
// after
long ns = Long.parseLong(props.getProperty("idle.ns"));
ns = Math.max(0, Math.min(ns, TimeUnit.SECONDS.toNanos(1)));
ctx.idleSleepDurationNs(ns);

Defensive patterns

Strategy: validation

Validate before calling

if (ns < 0 || ns > TimeUnit.SECONDS.toNanos(1)) { throw new IllegalArgumentException("idleSleepDurationNs out of range: " + ns); }

Type guard

long clampIdleNs(long ns) { return Math.max(0, Math.min(ns, TimeUnit.SECONDS.toNanos(1))); }

Try / catch

try { ctx.idleSleepDurationNs(ns); } catch (ConfigurationException e) { if (e.getMessage().startsWith("Invalid idle sleep duration")) { ctx.idleSleepDurationNs(clampIdleNs(ns)); } else throw e; }

Prevention

Clamp values read from external configuration
Watch unit mistakes: property files often specify ms, the API takes ns
Prefer ctx.idleStrategy(...) with a known strategy over raw ns tuning

When it happens

Trigger: Calling ctx.idleSleepDurationNs(ns) with ns < 0 or ns > TimeUnit.SECONDS.toNanos(1), then Aeron.connect(ctx); loading the value from a config property without clamping (e.g. a mistyped value like -1 or 10_000_000_000).

Common situations: External configuration files where the duration was entered in milliseconds instead of nanoseconds (value far above 1s); sign errors when tuning idle behavior; copying a duration computed for another purpose.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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

Appendix: source

Thrown at aeron-client/src/main/java/io/aeron/Aeron.java:1213

            if (clientName.length() > MAX_CLIENT_NAME_LENGTH)
            {
                throw new ConfigurationException("clientName length must <= " + MAX_CLIENT_NAME_LENGTH);
            }

            if (null == epochClock)
            {
                epochClock = SystemEpochClock.INSTANCE;
            }

            if (null == nanoClock)
            {
                nanoClock = SystemNanoClock.INSTANCE;
            }

            if (idleSleepDurationNs < 0 || idleSleepDurationNs > TimeUnit.SECONDS.toNanos(1))
            {
                throw new ConfigurationException("Invalid idle sleep duration: " + idleSleepDurationNs + "ns");
            }

            if (null == idleStrategy)
            {
                idleStrategy = new SleepingMillisIdleStrategy(TimeUnit.NANOSECONDS.toMillis(idleSleepDurationNs));
            }

            if (null == awaitingIdleStrategy)
            {
                awaitingIdleStrategy = new SleepingMillisIdleStrategy(Configuration.AWAITING_IDLE_SLEEP_MS);
            }

            connectToDriver();
            filePageSize = driverFilePageSize(cncMetaDataBuffer);

            interServiceTimeoutNs = CncFileDescriptor.clientLivenessTimeoutNs(cncMetaDataBuffer);
            if (interServiceTimeoutNs <= keepAliveIntervalNs)
            {

View on GitHub (pinned to 6d60124e15)