phacility/phabricator · warning · PhutilArgumentUsageException

When using "--caches", you must select at least one valid ca

Error message

When using "--caches", you must select at least one valid cache to purge.

What it means

Thrown by bin/cache purge when, after splitting --caches and keeping recognized keys, the selected purger set is empty. In practice it is nearly unreachable from the CLI because any unrecognized or empty token triggers the per-key error (202) first; it exists as a defensive fallback, e.g. for code that constructs the workflow programmatically.

Source

Thrown at src/applications/cache/management/PhabricatorCacheManagementPurgeWorkflow.php:60

    if ($is_all) {
      $purgers = $all_purgers;
    } else {
      $key_list = preg_split('/[\s,]+/', $key_list);
      $purgers = array();
      foreach ($key_list as $key) {
        if (isset($all_purgers[$key])) {
          $purgers[$key] = $all_purgers[$key];
        } else {
          throw new PhutilArgumentUsageException(
            pht(
              'Cache purger "%s" is not recognized. Available caches '.
              'are: %s.',
              $key,
              implode(', ', array_keys($all_purgers))));
        }
      }
      if (!$purgers) {
        throw new PhutilArgumentUsageException(
          pht(
            'When using "--caches", you must select at least one valid '.
            'cache to purge.'));
      }
    }

    $viewer = $this->getViewer();

    foreach ($purgers as $key => $purger) {
      $purger->setViewer($viewer);

      echo tsprintf(
        "%s\n",
        pht(
          'Purging "%s" cache...',
          $key));

      $purger->purgeCache();

View on GitHub (pinned to 5720a38cfe)

Solutions

Pass at least one valid cache key: 'bin/cache purge --caches general'.
In wrapper code, assert count($purgers) >= 1 after filtering and before proceeding.
Log the raw --caches value to spot over-aggressive sanitization that strips every token.

Defensive patterns

Strategy: validation

Validate before calling

$valid = array_keys(PhabricatorCachePurger::getAllPurgers());
$wanted = preg_split('/[\s,]+/', (string)$args->getArg('caches'), -1, PREG_SPLIT_NO_EMPTY);
$selected = array_values(array_intersect($wanted, $valid));
if (!$selected) {
  fwrite(STDERR, "No valid caches selected; nothing to do.\n");
  exit(1);
}
$args->setArg('caches', implode(',', $selected));

Try / catch

try {
  $workflow->execute($args);
} catch (PhutilArgumentUsageException $ex) {
  fwrite(STDERR, $ex->getMessage()."\n");
  exit(1);
}

Prevention

Filter the cache list against registered purgers before invoking execute().
Assert count($selected) >= 1 in wrappers after any sanitization step.
Log the raw input list when it sanitizes down to nothing.

When it happens

Trigger: Programmatically invoking the workflow with a caches value that resolves to zero purgers after filtering; modified/extended workflow code that pre-filters $key_list.

Common situations: Custom wrappers that sanitize the cache list before calling execute() and accidentally filter everything out; empty-string tokens in exotic inputs.

Related errors

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