apache/cassandra · error · IllegalArgumentException

Artificial latency limit is

Error message

Artificial latency limit is ${nanoLimit}ns; tried to set ${nanos}ns

What it means

ArtificialLatency.setArtificialLatencies enforces an upper bound on configured artificial latencies (nanoLimit, e.g. from the artificial latency limit config) to prevent accidentally huge message delays. When a single (non-per-DC) latency value parses to nanos >= nanoLimit, an IllegalArgumentException is thrown reporting both the limit and the attempted value.

Solutions

Lower the configured latency so it is below the reported nanoLimit
If a larger value is genuinely needed, raise the artificial latency limit setting (test.jupiter.limit or equivalent advanced config) before calling setArtificialLatencies
Check for missing commas if intending per-DC latencies — a malformed per-DC string is parsed as a single oversized value
Convert units carefully: the limit is in nanoseconds, the input in milliseconds

Example fix

// before (limit is 1000000ns)
ArtificialLatency.setArtificialLatencies("5ms"); // 5,000,000ns >= limit

// after
ArtificialLatency.setArtificialLatencies("0.5ms"); // 500,000ns < limit

Defensive patterns

Strategy: validation

Validate before calling

long nanos = TimeUnit.MILLISECONDS.toNanos(Long.parseLong(latency.replace("ms","")));
if (nanos >= nanoLimit) throw new Error("Latency " + nanos + "ns exceeds limit " + nanoLimit + "ns");

Try / catch

try { ArtificialLatency.setArtificialLatencies(latencies); }
catch (IllegalArgumentException e) { logger.error("Latency above allowed limit: {}", e.getMessage()); }

Prevention

Check the configured artificial latency limit before setting values
Remember the limit is in nanoseconds while input is milliseconds
Validate per-DC strings have correct comma/colon structure so values parse as intended

When it happens

Trigger: Calling setArtificialLatencies with a single latency string whose millisecond value converts to nanoseconds greater than or equal to the configured nanoLimit (e.g. setting several seconds when the allowed maximum is well below that).

Common situations: Misconfigured test_latency/artificial latency in cassandra.yaml (comma expected but absent, so whole string treated as one value); trying to simulate multi-second delays exceeding the safety limit; confusion between ms and ns units leading to oversized values.

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 apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/851cf4f6aabdb239. Report an issue: GitHub.

Appendix: source

Thrown at src/java/org/apache/cassandra/net/ArtificialLatency.java:309

    }

    public static void setArtificialLatencies(String latencies)
    {
        setArtificialLatencies(latencies, parseNanos(ARTIFICIAL_LATENCY_LIMIT.getString()));
    }

    public static void unsafeSetArtificialLatencies(String latencies)
    {
        setArtificialLatencies(latencies, Long.MAX_VALUE);
    }

    private static synchronized void setArtificialLatencies(String latencies, long nanoLimit)
    {
        if (latencies.indexOf(',') < 0)
        {
            long nanos = parseNanos(latencies);
            if (nanos >= nanoLimit)
                throw new IllegalArgumentException("Artificial latency limit is " + nanoLimit + "ns; tried to set " + nanos + "ns");
            artificialLatencyNanos = ignore -> nanos;
        }
        else
        {
            String[] parse = latencies.split(",");
            Object2LongHashMap<String> dcLatencies = new Object2LongHashMap<>(-1L);
            for (int i = 0 ; i < parse.length ; ++i)
            {
                String[] subparse = parse[i].split(":");
                String dc = subparse[0];
                long nanos = parseNanos(subparse[1]);
                if (nanos >= nanoLimit)
                    throw new IllegalArgumentException("Artificial latency limit is " + nanoLimit + "ns; tried to set " + nanos + "ns");
                dcLatencies.put(dc, nanos);
            }
            artificialLatencyNanos = addr -> {
                Directory directory = ClusterMetadata.current().directory;
                NodeId nodeId = directory.peerId(addr);

View on GitHub (pinned to 88fd0f6a0e)