What causes "Got a null list of results" in apache/druid?

Fix the Sequence/QueryRunner implementation to return an empty List instead of null from toList()

apache/druid · error · ISE

Got a null list of results

Error message

Got a null list of results

What it means

Defensive check immediately after result.toList() in ChainedExecutionQueryRunner.call(): even if the Sequence is non-null, its toList() materialization returned null, which the query engine treats as an impossible state. This guards against Sequence implementations that return null instead of an empty list.

Source

Thrown at processing/src/main/java/org/apache/druid/query/ChainedExecutionQueryRunner.java:120

                          }

                          final AbstractPrioritizedQueryRunnerCallable<Iterable<T>, T> callable = new AbstractPrioritizedQueryRunnerCallable<>(
                              priority,
                              input
                          )
                          {
                            @Override
                            public Iterable<T> call()
                            {
                              try {
                                Sequence<T> result = input.run(threadSafeQueryPlus, responseContext);
                                if (result == null) {
                                  throw new ISE("Got a null result! Segments are missing!");
                                }

                                List<T> retVal = result.toList();
                                if (retVal == null) {
                                  throw new ISE("Got a null list of results");
                                }

                                return retVal;
                              }
                              catch (QueryInterruptedException e) {
                                throw new RuntimeException(e);
                              }
                              catch (QueryTimeoutException e) {
                                throw e;
                              }
                              catch (Exception e) {
                                if (query.context().isDebug()) {
                                  log.error(e, "Exception with one of the sequences!");
                                } else {
                                  log.noStackTrace().error(e, "Exception with one of the sequences!");
                                }
                                Throwables.throwIfUnchecked(e);
                                throw new RuntimeException(e);

View on GitHub (pinned to 9b90983fd2)

Solutions

Fix the Sequence/QueryRunner implementation to return an empty List instead of null from toList()
Use Sequences.toList(...) or wrap with Sequences.simple(...) so the standard materialization path is used
Search the extension classpath for custom Sequence classes and validate them with a unit test materializing an empty result
Upgrade extensions to match the Druid core version in use

Example fix

// before
List<T> toList() {
  return null; // nothing collected
}
// after
List<T> toList() {
  return collected == null ? Collections.emptyList() : collected;
}

Defensive patterns

Strategy: type-guard

Validate before calling

// unit-test custom Sequence adapters: materialize an empty result
List<Object> out = Sequences.toList(myAdapter.run(q, ctx), ( Accumulator ) null);

Type guard

boolean isValidToList(Sequence<?> seq) {
  if (seq == null) return false;
  List<?> l = seq.toList();
  return l != null;
}

Try / catch

try {
  List<T> rows = runQuery();
} catch (IllegalStateException e) {
  if ("Got a null list of results".equals(e.getMessage())) {
    // fix/replace the Sequence adapter returning null
  }
}

Prevention

Never return null from Sequence.toList(); return Collections.emptyList()
Use core Sequences helpers instead of custom materialization
Test extensions against an empty datasource to catch null-returning adapters

When it happens

Trigger: A Sequence implementation whose toList() returns null instead of Sequences.toList contract of an empty list; custom Sequence wrappers or extension code materializing results incorrectly; corrupt result adapters inserted between segment runner and the chain.

Common situations: Custom QueryRunner/Sequence implementations from extensions or tests; newer Druid API changes where Sequence.toList semantics differ from a hand-rolled adapter; memory-pressure paths that silently null out buffers in non-standard forks.

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