apache/pulsar · error · IllegalArgumentException

first delta must be > 0, got ${deltas.get(0)}

Error message

first delta must be > 0, got ${deltas.get(0)}

What it means

IllegalArgumentException thrown by the compact constructor of the SequenceKeysDeltas record in Option.java. The library enforces that a sequence-key delta list starts with a strictly positive first delta, because the first delta establishes the initial offset of the sequence; a zero or negative value would produce an invalid or ambiguous starting sequence.

Source

Thrown at pulsar-metadata/src/main/java/org/apache/pulsar/metadata/api/Option.java:94

     * <p>The {@code Stat} returned from the {@code put} carries the actual generated path. Pair
     * with {@link MetadataStore#subscribeSequence} to receive notifications as new sequence keys
     * are created.
     *
     * <p>Constraints: {@code deltas} must be non-empty, the first delta must be {@code > 0}, and
     * the rest must be {@code >= 0}. On Oxia a {@link PartitionKey} must also be provided.
     * Backends without native sequence-key support synthesize the same key format using a
     * sidecar counter document and CAS.
     *
     * @param deltas per-dimension increments
     */
    record SequenceKeysDeltas(List<Long> deltas) implements Option {

        public SequenceKeysDeltas {
            if (deltas == null || deltas.isEmpty()) {
                throw new IllegalArgumentException("SequenceKeysDeltas requires at least one delta");
            }
            if (deltas.get(0) <= 0) {
                throw new IllegalArgumentException("first delta must be > 0, got " + deltas.get(0));
            }
            for (int i = 1; i < deltas.size(); i++) {
                if (deltas.get(i) < 0) {
                    throw new IllegalArgumentException(
                            "delta at index " + i + " must be >= 0, got " + deltas.get(i));
                }
            }
            deltas = List.copyOf(deltas);
        }
    }
}

View on GitHub (pinned to 820761864e)

Solutions

1. Ensure the first element of the deltas list is strictly positive before constructing SequenceKeysDeltas
2. Fix the delta-computation logic so the first delta is derived as (firstKey - baseKey) with baseKey < firstKey
3. Pre-validate inputs with an explicit check and produce a domain-specific error instead of a raw IllegalArgumentException

Example fix

// before
SequenceKeysDeltas d = new SequenceKeysDeltas(List.of(0L, 3L)); // throws
// after
List<Long> deltas = computeDeltas(keys);
if (deltas.isEmpty() || deltas.get(0) <= 0) {
    throw new IllegalStateException("first delta must be positive, got " + (deltas.isEmpty() ? "none" : deltas.get(0)));
}
SequenceKeysDeltas d = new SequenceKeysDeltas(deltas);

if (deltas == null || deltas.isEmpty()) throw new IllegalArgumentException("deltas required");
if (deltas.get(0) <= 0) throw new IllegalArgumentException("first delta must be > 0");
for (int i = 1; i < deltas.size(); i++) { if (deltas.get(i) < 0) throw new IllegalArgumentException("negative delta at " + i); }

static boolean isValidDeltas(List<Long> deltas) {
    return deltas != null && !deltas.isEmpty() && deltas.get(0) > 0
        && deltas.stream().skip(1).allMatch(d -> d >= 0);
}

When it happens

Trigger: Constructing SequenceKeysDeltas (directly or via a metadata API that builds one) with a list whose first element is <= 0, e.g. List.of(0L, 5L) or a computed first delta of 0 when two consecutive keys are equal.

Common situations: Passing empty or degenerate delta lists computed from log/event sequences; off-by-one in delta computation producing 0 for the first entry; deserializing user-supplied delta arrays without pre-validation.

Related errors

• delta at index ${i} must be >= 0, got ${deltas.get(i)}
• Timeout during update managedLedger's properties
• Failed to initialize BookKeeper metadata
• Error while scanning ledgers for ${namespaceName}
• Must have at least 1 segment

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/a075a461ab39fb45. Report an issue: GitHub.