phacility/phabricator · error · PhutilArgumentUsageException

Query "%s" is unknown. To run a builtin query like "all" or

Error message

Query "%s" is unknown. To run a builtin query like "all" or "active", also specify the search engine with "--class".

What it means

Each --query key is first looked up among the chosen engine's builtin queries and then among saved queries in the database (PhabricatorSavedQueryQuery). If the key is unknown and no --class was supplied, this usage exception explains that builtin names like 'all' or 'active' need --class to know which engine to use. Without a class, only database-stored saved-query keys can be resolved.

Source

Thrown at src/applications/transactions/bulk/management/PhabricatorBulkManagementExportWorkflow.php:233

    }

    $queries = array();
    foreach ($query_keys as $query_key) {
      if ($engine) {
        if ($engine->isBuiltinQuery($query_key)) {
          $queries[$query_key] = $engine->buildSavedQueryFromBuiltin(
            $query_key);
          continue;
        }
      }

      $saved_query = id(new PhabricatorSavedQueryQuery())
        ->setViewer($viewer)
        ->withQueryKeys(array($query_key))
        ->executeOne();
      if (!$saved_query) {
        if (!$engine) {
          throw new PhutilArgumentUsageException(
            pht(
              'Query "%s" is unknown. To run a builtin query like "all" or '.
              '"active", also specify the search engine with "--class".',
              $query_key));
        } else {
          throw new PhutilArgumentUsageException(
            pht(
              'Query "%s" is not a recognized query for class "%s".',
              $query_key,
              get_class($engine)));
        }
      }

      $queries[$query_key] = $saved_query;
    }

    // If we don't have an engine from "--class", fill it in by looking at the
    // class of the first query.

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Add --class <EngineClassName> so builtin names like all or active resolve against that engine.
2. Use a real saved query key: run the search in the web UI and copy the queryKey parameter from the URL.
3. Recreate the deleted saved query in the UI and use its new key.

Example fix

# before
bin/bulk export --query all --output -
# after
bin/bulk export --class ManiphestTaskSearchEngine --query all --output -

# builtin names always need an engine; enforce the pairing
if [[ "$QUERY" == all || "$QUERY" == active ]]; then
  test -n "$ENGINE_CLASS" || { echo 'builtin queries require --class' >&2; exit 2; }
fi

Catch PhutilArgumentUsageException, detect 'is unknown', and re-emit the hint about --class plus a link to the saved-query UI.

When it happens

Trigger: Running `bin/bulk export --query all --output -` with no --class; passing a saved-query key that was deleted or copied from a different install (executeOne returns nothing).

Common situations: Copy-pasting '--query all' from documentation without the accompanying --class; stale query keys after someone deleted the saved search; migrating keys between test and prod.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Specify one or more queries to export with "--query".
• Query "%s" is not a recognized query for class "%s".
• Specified queries use different engines: query "%s" uses eng
• Use "--output <path>" to specify an output file, or "--outpu
• Flag "--overwrite" has no effect when outputting to stdout.

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