apache/druid · error · MSQException

MSQFault from worker error report

Error message

MSQFault from worker error report

What it means

WorkerImpl.run converts any worker failure into an MSQException carrying the fault from the MSQErrorReport. When the underlying throwable is not an MSQException (and not a cancellation), it is wrapped: 'MSQFault from worker error report' is the generic message whose real cause is the attached fault. The fault is also posted to the controller as a worker error beforehand.

Source

Thrown at multi-stage-query/src/main/java/org/apache/druid/msq/exec/WorkerImpl.java:211

      // Report query metrics
      reportQueryMetrics(maybeErrorReport.isEmpty(), stopwatch.millisElapsed());

      if (maybeErrorReport.isPresent()) {
        final MSQErrorReport errorReport = maybeErrorReport.get();
        final String logMessage = MSQTasks.errorReportToLogMessage(errorReport, context.isDebug());
        log.warn("%s", logMessage);

        // Inform controller of any errors that occur, unless we were canceled. This prevents attempting to contact
        // the controller after cancellation due to controller failure. For situations where the worker is canceled
        // but the controller is still alive, cancellation propagates to the controller in other ways. (For example,
        // with single-shot tasks, the controller notices the task fails.)
        if (!(errorReport.getFault() instanceof CanceledFault)) {
          controllerClient.postWorkerError(errorReport);
        }

        if (t != null) {
          Throwables.throwIfInstanceOf(t, MSQException.class);
          throw new MSQException(t, maybeErrorReport.get().getFault());
        } else {
          throw new MSQException(maybeErrorReport.get().getFault());
        }
      }
    }
    catch (IOException e) {
      throw new RuntimeException(e);
    }
    finally {
      runFuture.set(null);
    }
  }

  @SuppressWarnings("unchecked")
  private void reportQueryMetrics(boolean success, long time)
  {
    long cpuTimeNs = 0L;
    for (final CounterTracker tracker : stageCounters.values()) {

View on GitHub (pinned to 9b90983fd2)

Solutions

  1. Inspect the MSQFault details (errorCode/errorMessage) in the MSQErrorReport or the query's error output — the root cause is there, not in this wrapper message
  2. Check worker (Peon/Task) logs for the full stack trace of the underlying throwable
  3. Fix the underlying fault per its specific code (e.g. resource limits, bad input)
  4. Retry the query after correcting the root cause
Defensive patterns

Strategy: try-catch

Try / catch

try { runWorker(); } catch (MSQException e) { MSQFault fault = e.getFault(); log.error("worker fault {}: {}", fault.getErrorCode(), fault.getErrorMessage(), e.getCause()); }

Prevention

When it happens

Trigger: A worker task fails with a non-MSQException throwable (or with t==null after an error report was generated), so run() rethrows new MSQException(fault) using the error report's fault — surfacing the underlying fault details in the report, not this generic message.

Common situations: Worker-side engine failures (IO, serialization, channel errors) during stage execution; inspecting only the top-level message instead of the fault/cause in the error report shown by the SQL response or controller logs.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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