phacility/phabricator · error · Exception

Query (of class "%s") overheated: examined more than %s raw

Error message

Query (of class "%s") overheated: examined more than %s raw rows without finding %s visible objects.

What it means

Thrown by PhabricatorPolicyAwareQuery when a policy-filtered query has examined more raw rows than its overheat budget — computed as the number of results still needed times 10 — without accumulating enough policy-visible objects. Phabricator pages through raw database rows and filters by policy in the application; without a cap, a viewer who can see almost nothing would force a full table scan. Overheating aborts the query to protect the database; setReturnPartialResultsOnOverheat() or setDisableOverheating() change that behavior, and getIsOverheated() reports it afterwards.

Source

Thrown at src/infrastructure/query/policy/PhabricatorPolicyAwareQuery.php:342

      if (!$this->rawResultLimit) {
        // If we don't have a load count, we loaded all the results. We do
        // not need to load another page.
        break;
      }

      if (count($page) < $this->rawResultLimit) {
        // If we have a load count but the unfiltered results contained fewer
        // objects, we know this was the last page of objects; we do not need
        // to load another page because we can deduce it would be empty.
        break;
      }

      if (!$this->disableOverheating) {
        if ($overheat_limit && ($total_seen >= $overheat_limit)) {
          $this->isOverheated = true;

          if (!$this->returnPartialResultsOnOverheat) {
            throw new Exception(
              pht(
                'Query (of class "%s") overheated: examined more than %s '.
                'raw rows without finding %s visible objects.',
                get_class($this),
                new PhutilNumber($overheat_limit),
                new PhutilNumber($need)));
          }

          break;
        }
      }
    } while (true);

    $results = $this->didLoadResults($results);

    return $results;
  }

View on GitHub (pinned to 5720a38cfe)

Solutions

Narrow the query with real constraints (withStatuses, withDateCreated, projects, etc.) so the database returns fewer raw rows
If partial results are acceptable, call setReturnPartialResultsOnOverheat(true) and check getIsOverheated() to warn the user
For trusted internal batch work (exports, daemons), call setDisableOverheating(true) — only where you are certain the row volume is bounded
Review the viewer's policy configuration: if they should see these objects, fix the policy so rows are not discarded after fetching

Example fix

// before
$results = $query->setViewer($user)->execute();

// after: accept partial results and surface that fact
$results = id(clone $query)
  ->setViewer($user)
  ->setReturnPartialResultsOnOverheat(true)
  ->execute();
if ($query->getIsOverheated()) {
  // tell the user results are truncated; suggest narrower filters
}

Defensive patterns

Strategy: fallback

Validate before calling

// If you cannot afford partial results, bound the query instead:
// add real constraints so raw rows are unlikely to hit 10x the limit.
$query->withDateCreatedBetween($start, $end); // etc.
// Optionally pre-flight with a tiny limit to estimate selectivity:
$probe = id(clone $query)->setLimit(1)->execute();

Try / catch

try {
  $results = $query->execute();
} catch (Exception $ex) {
  if (preg_match('/overheated/', $ex->getMessage())) {
    // fall back: accept truncated results and flag them to the user
    $results = id(clone $query)
      ->setReturnPartialResultsOnOverheat(true)
      ->execute();
    // $query->getIsOverheated() === true here
  } else {
    throw $ex;
  }
}

Prevention

For untrusted/broad viewers, always add selective constraints instead of listing everything
Use setReturnPartialResultsOnOverheat(true) plus getIsOverheated() for user-facing search pages
Reserve setDisableOverheating(true) for trusted, bounded batch jobs

When it happens

Trigger: A viewer whose policies exclude nearly all objects running a broad query (large 'all' queries as a restricted user); queries whose WHERE clause matches many rows but whose policy filtering discards most of them; setting a very small result limit while raw matches are huge.

Common situations: New restricted/bot accounts listing large object collections; mail/notification generation as a restricted daemon user; dashboards running aggregate queries for low-privilege viewers.

Related errors

AI-assisted analysis of phacility/phabricator@5720a38cfe (2026-08-21). Data as JSON: /api/errors/0f0981c2e9018248. Report an issue: GitHub.