apache/druid · error · IllegalArgumentException

Cannot pipeline with fault tolerance

Error message

Cannot pipeline with fault tolerance

What it means

Pipelining and fault tolerance are mutually exclusive execution modes in the MSQ kernel; the constructor throws IAE when both pipeline and faultTolerance are true. Pipelined stages rely on in-memory exchange while fault tolerance requires checkpointed, replayable stages, so the combination is unsupported.

Source

Thrown at multi-stage-query/src/main/java/org/apache/druid/msq/kernel/controller/ControllerQueryKernelConfig.java:74

      @Nullable String controllerHost,
      @Nullable List<String> workerIds,
      Map<String, Object> workerContextMap
  )
  {
    if (maxRetainedPartitionSketchBytes <= 0) {
      throw new IAE("maxRetainedPartitionSketchBytes must be positive");
    }

    if (pipeline && maxConcurrentStages < 2) {
      throw new IAE("maxConcurrentStagesPerWorker must be >= 2 when pipelining");
    }

    if (maxConcurrentStages <= 0) {
      throw new IAE("maxConcurrentStagesPerWorker must be positive");
    }

    if (pipeline && faultTolerance) {
      throw new IAE("Cannot pipeline with fault tolerance");
    }

    if (pipeline && durableStorage) {
      throw new IAE("Cannot pipeline with durable storage");
    }

    if (faultTolerance && !durableStorage) {
      throw new IAE("Cannot have fault tolerance without durable storage");
    }

    this.maxRetainedPartitionSketchBytes = maxRetainedPartitionSketchBytes;
    this.maxConcurrentStages = maxConcurrentStages;
    this.pipeline = pipeline;
    this.durableStorage = durableStorage;
    this.faultTolerance = faultTolerance;
    this.destination = destination;
    this.controllerHost = controllerHost;
    this.workerIds = workerIds;

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Disable fault tolerance (and its durable-storage prerequisite) to keep pipelining enabled.
2. Or disable pipelining to keep fault tolerance.
3. In query-building code, enforce exclusivity before submitting: if (pipeline && faultTolerance) choose one and clear the other context key.

Example fix

// before
context.put("pipelinedStagesEnabled", true);
context.put("faultTolerance", true);

// after
context.put("pipelinedStagesEnabled", true);
context.put("faultTolerance", false); // pick one mode

if (ctx.getBoolean("pipelinedStagesEnabled") && ctx.getBoolean("faultTolerance")) {
  throw new IllegalArgumentException("Enable either pipelining or fault tolerance, not both");
}

try {
  submitQuery(ctx);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("Cannot pipeline with fault tolerance")) {
    ctx.put("faultTolerance", false);
    submitQuery(ctx);
  }
}

When it happens

Trigger: Constructing ControllerQueryKernelConfig with pipeline=true and faultTolerance=true, e.g. query context having both pipelining enabled and faultTolerance/durablyStoreTempResults-style fault-tolerance flags set.

Common situations: Users enabling fault tolerance for long-running ingestion while a cluster default turns on pipelining; combining tuning advice from two different Druid versions where defaults changed.

Understand the failure class

Background: "mutually exclusive" flag errors: what "can't supply both nx and xx", "--raw is not compatible with -i" and "cannot be used with" mean, and how to fix them — this error's family across 29 libraries.

Related errors

• Cannot pipeline with durable storage
• maxConcurrentStagesPerWorker must be >= 2 when pipelining
• Cannot have fault tolerance without durable storage
• NotEnoughMemoryFault
• Invalid value of %s.maxThreads[%d]

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