What causes "'skip' must be greater than zero" in apache/druid?

Pass a skip value >= 1; if you don't want to skip, use the baseSequence directly

apache/druid · error · IllegalArgumentException

'skip' must be greater than zero

Error message

'skip' must be greater than zero

What it means

SkippingSequence wraps a base Sequence and skips N leading elements per iteration. The constructor validates that skip >= 1; a skip of 0 or negative is meaningless (skipping nothing or backwards) and throws IAE immediately at construction.

Source

Thrown at processing/src/main/java/org/apache/druid/java/util/common/guava/SkippingSequence.java:40

import org.apache.druid.java.util.common.IAE;

import java.io.IOException;

/**
 * A Sequence that skips the first few elements.
 */
public class SkippingSequence<T> extends YieldingSequenceBase<T>
{
  private final Sequence<T> baseSequence;
  private final long skip;

  public SkippingSequence(Sequence<T> baseSequence, long skip)
  {
    this.baseSequence = baseSequence;
    this.skip = skip;

    if (skip < 1) {
      throw new IAE("'skip' must be greater than zero");
    }
  }

  @Override
  public <OutType> Yielder<OutType> toYielder(OutType initValue, YieldingAccumulator<OutType, T> accumulator)
  {
    final SkippingYieldingAccumulator<OutType> skippingAccumulator = new SkippingYieldingAccumulator<>(accumulator);
    return wrapYielder(baseSequence.toYielder(initValue, skippingAccumulator), skippingAccumulator);
  }

  private <OutType> Yielder<OutType> wrapYielder(
      final Yielder<OutType> yielder,
      final SkippingYieldingAccumulator<OutType> accumulator
  )
  {
    return new Yielder<>()
    {
      @Override

View on GitHub (pinned to 9b90983fd2)

Solutions

Pass a skip value >= 1; if you don't want to skip, use the baseSequence directly
Clamp or skip the wrapper: only wrap in SkippingSequence when offset > 0
Validate the offset/skip parameter at the API boundary before constructing the sequence

Example fix

// before
Sequence<T> seq = new SkippingSequence<>(base, offset); // offset=0 -> IAE
// after
Sequence<T> seq = offset > 0 ? new SkippingSequence<>(base, offset) : base;

Defensive patterns

Strategy: validation

Validate before calling

if (skip < 1) throw new IllegalArgumentException("skip must be >= 1");
Sequence<T> seq = skip > 0 ? new SkippingSequence<>(base, skip) : base;

Type guard

boolean validSkip = skip >= 1;

Try / catch

try { seq = new SkippingSequence<>(base, skip); } catch (IllegalArgumentException e) { seq = base; }

Prevention

Compute skip from page math with Math.max(1, page*pageSize) only when paging is active
Validate offset/skip parameters at the API boundary
Prefer the base sequence directly when skip == 0

When it happens

Trigger: new SkippingSequence(baseSequence, 0) or negative skip — e.g. from a limit/offset calculation that produced a non-positive skip value.

Common situations: Paging implementations computing skip = page * pageSize when page=0; user-supplied offset configs that bypass validation upstream.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/5c5fd4b1cdcbda68. Report an issue: GitHub.