apache/druid · error · DruidException

Failed to handle query

Error message

Failed to handle query: %s

What it means

SqlTaskResource.doPost catches AssertionError and Exception around MSQ SQL query submission and returns a DEVELOPER-persona UNCATEGORIZED DruidException via buildNonOkResponse. It is a catch-all wrapper: the message carries the sqlQueryId, and the original failure is logged without stack trace and reported on the statement reporter. The real cause is whatever planning/validation/ingestion threw.

Solutions

1. Read the returned response body / broker logs at the reported stack for the underlying cause and fix the SQL or context parameters
2. Check that referenced datasources, columns, and functions exist and are supported by the MSQ engine
3. Verify cluster health (overlord, workers) and task capacity before retrying
4. If an AssertionError persists, capture the full query and report it as a bug with Druid version

Example fix

// before
client.execute("SELECT NONEXISTENT_FUNC(x) FROM tbl")
// after
client.execute("SELECT SUM(x) FROM tbl") // use a supported function; validate SQL first

// validate SQL before submitting
// e.g. run EXPLAIN PLAN FOR <sql> against /druid/v2/sql first, and check datasource existence via /druid/coordinator/v1/datasources

if (!(e instanceof org.apache.druid.java.util.common.DruidException)) { wrapInDruidException(e); }

try { submitQuery(sql); } catch (DruidException | AssertionError e) { log.error("MSQ submit failed for %s", sqlQueryId, e); return Response.status(500).entity(e.getMessage()).build(); }

When it happens

Trigger: POSTing a SQL query to /druid/v2/sql/statements when Calcite planning or validation throws (bad SQL syntax, unknown function/table, planning AssertionError), or any exception during MSQ task submission (access denial, bad context params, cluster issues).

Common situations: Typos in SQL, referencing nonexistent datasources/columns, unsupported SQL features,Calcite assertion failures during planning, MSQ worker/task launch failures surfacing at submit time.

Understand the failure class

Background: "query failed", "%w: SQL error" — wrapped database query errors in Go libraries explained — this error's family across 3 libraries.

Related errors

• Failed to handle query
• Cannot filter datasource
• Cannot handle constant condition
• Cannot handle equality condition involving left-hand…
• Cannot handle non-equijoin condition

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

Appendix: source

Thrown at multi-stage-query/src/main/java/org/apache/druid/msq/sql/resources/SqlTaskResource.java:181

    }
    catch (QueryException queryException) {
      stmt.reporter().failed(queryException);
      final DruidException underlyingException = DruidException.fromFailure(new QueryExceptionCompat(queryException));
      return buildNonOkResponse(sqlQueryId, underlyingException);
    }
    catch (ForbiddenException e) {
      log.debug("Got forbidden request for reason [%s]", e.getErrorMessage());
      return buildNonOkResponse(
          "forbidden",
          DruidException.forPersona(DruidException.Persona.USER)
                        .ofCategory(DruidException.Category.FORBIDDEN)
                        .build(Access.DEFAULT_ERROR_MESSAGE)
      );
    }
    // Calcite throws java.lang.AssertionError at various points in planning/validation.
    catch (AssertionError | Exception e) {
      stmt.reporter().failed(e);
      log.noStackTrace().warn(e, "Failed to handle query: %s", sqlQueryId);

      return buildNonOkResponse(
          sqlQueryId,
          DruidException.forPersona(DruidException.Persona.DEVELOPER)
                        .ofCategory(DruidException.Category.UNCATEGORIZED)
                        .build("%s", e.getMessage())
      );
    }
    finally {
      stmt.close();
    }
  }

  /**
   * Generates a task response using {@link SqlTaskStatus}.
   */
  private Response buildTaskResponse(Sequence<Object[]> sequence) throws IOException
  {

View on GitHub (pinned to 9b90983fd2)