apache/druid · error · DruidException

Failed to handle query

Error message

Failed to handle query [%s]

What it means

The /druid/v2/sql/statements POST endpoint caught an AssertionError or Exception while planning/submitting an async SQL query. The query is marked failed and the server responds with an UNCATEGORIZED DEVELOPER-persona DruidException wrapped as this message.

Solutions

1. Read the 'error' details in the HTTP response — the root cause (SQL parse/plan error) is included
2. Fix the SQL: check identifiers, function support, and syntax
3. Enable debug logging (isDebug) on the broker for full stack traces during development
4. Check authorizer config if the failure is a Forbidden/assertion error

Example fix

// before: query with unsupported function
SELECT REGEXP_SUBSTR(col, 'a') FROM tbl

// after: use an MSQ-supported equivalent
SELECT REGEXP_EXTRACT(col, 'a', 1) FROM tbl

// Validate SQL locally before POSTing to /druid/v2/sql/statements
// Ensure body has {query, context}; check identifiers exist via information_schema
POST /druid/v2/sql?wrapQueryInStatements=false body: {"query":"EXPLAIN PLAN FOR " + sql}

try { postStatement(sql); } catch (DruidWebException e) { /* read response.error/errorMessage and correct the SQL accordingly */ }

When it happens

Trigger: POST /druid/v2/sql/statements where query validation/planning fails (SQL syntax errors, unknown columns/functions, authorization assertions, planning AssertionErrors from Calcite).

Common situations: Typos in SQL or object names; using functions not available in the MSQ engine; permission/authorization failures; Calcite assertion errors on unsupported query shapes; malformed JSON request body.

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/c646baf25be32761. Report an issue: GitHub.

Appendix: source

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

    }
    catch (DruidException e) {
      stmt.reporter().failed(e);
      return buildNonOkResponse(e);
    }
    catch (QueryException queryException) {
      stmt.reporter().failed(queryException);
      final DruidException underlyingException = DruidException.fromFailure(new QueryExceptionCompat(queryException));
      return buildNonOkResponse(underlyingException);
    }
    catch (ForbiddenException e) {
      log.debug("Got forbidden request for reason [%s]", e.getErrorMessage());
      return buildNonOkResponse(Forbidden.exception());
    }
    // Calcite throws java.lang.AssertionError at various points in planning/validation.
    catch (AssertionError | Exception e) {
      stmt.reporter().failed(e);
      if (isDebug) {
        log.warn(e, "Failed to handle query [%s]", sqlQueryId);
      } else {
        log.noStackTrace().warn(e, "Failed to handle query [%s]", sqlQueryId);
      }
      return buildNonOkResponse(
          DruidException.forPersona(DruidException.Persona.DEVELOPER)
                        .ofCategory(DruidException.Category.UNCATEGORIZED)
                        .build("%s", e.getMessage())
      );
    }
    finally {
      stmt.close();
      Thread.currentThread().setName(currThreadName);
    }
  }


  @GET
  @Path("/{id}")

View on GitHub (pinned to 9b90983fd2)