phacility/phabricator · warning · PhutilArgumentUsageException

Specify either --reset or --threshold.

Error message

Specify either --reset or --threshold.

What it means

`bin/search ngrams` requires exactly one of --reset or --threshold. Invoked with neither, it has no defined behavior (the workflow recomputes ngram stopwords per Ferret engine and must know the strategy), so it fails with this usage exception.

Solutions

1. Add a threshold: `bin/search ngrams --threshold 0.05` (a fraction strictly between 0.0 and 1.0)
2. Or reset: `bin/search ngrams --reset`
3. Check `bin/search help ngrams` for the intended workflow

Example fix

# before
bin/search ngrams

# after
bin/search ngrams --threshold 0.05

$isReset = !empty($args['reset']);
$threshold = $args['threshold'] ?? null;
if (!$isReset && $threshold === null) {
  // require exactly one of --reset / --threshold before invoking
}

When it happens

Trigger: Bare `bin/search ngrams` with no flags.

Common situations: Exploring the CLI expecting a status report; scripts where the flag argument was dropped during refactoring.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Provide a list of objects to index (like "D123"), or a set…
• Specify a commit to extract the diff from.
• Specify a content type to run rules for. For this object…
• Specify a numeric threshold between 0 and 1.
• Specify a query with --query.

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

Appendix: source

Thrown at src/applications/search/management/PhabricatorSearchManagementNgramsWorkflow.php:41

              'Prune ngrams present in more than this fraction of '.
              'documents. Provide a value between 0.0 and 1.0.'),
          ),
        ));
  }

  public function execute(PhutilArgumentParser $args) {
    $min_documents = 4096;

    $is_reset = $args->getArg('reset');
    $threshold = $args->getArg('threshold');

    if ($is_reset && $threshold !== null) {
      throw new PhutilArgumentUsageException(
        pht('Specify either --reset or --threshold, not both.'));
    }

    if (!$is_reset && $threshold === null) {
      throw new PhutilArgumentUsageException(
        pht('Specify either --reset or --threshold.'));
    }

    if (!$is_reset) {
      if (!is_numeric($threshold)) {
        throw new PhutilArgumentUsageException(
          pht('Specify a numeric threshold between 0 and 1.'));
      }

      $threshold = (double)$threshold;
      if ($threshold <= 0 || $threshold >= 1) {
        throw new PhutilArgumentUsageException(
          pht('Threshold must be greater than 0.0 and less than 1.0.'));
      }
    }

    $all_objects = id(new PhutilClassMapQuery())
      ->setAncestorClass('PhabricatorFerretInterface')

View on GitHub (pinned to 5720a38cfe)