phacility/phabricator · warning · PhutilArgumentUsageException

Specify a numeric threshold between 0 and 1.

Error message

Specify a numeric threshold between 0 and 1.

What it means

When --threshold is given to `bin/search ngrams`, is_numeric() is applied before the value is cast to double and used as a document-frequency fraction. Any non-null value failing is_numeric (empty string, 'auto', '50%', '1e', arrays) triggers this usage exception before any database work starts.

Source

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

  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')
      ->execute();

    foreach ($all_objects as $object) {
      $engine = $object->newFerretEngine();
      $conn = $object->establishConnection('w');
      $display_name = get_class($object);

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Pass a bare decimal fraction: `--threshold 0.05`
2. Remove units like % - the value is a ratio, not a percentage
3. Quote the argument to keep the shell from mangling it

Example fix

# before
bin/search ngrams --threshold 5%

# after
bin/search ngrams --threshold 0.05

if (!is_numeric($threshold)) {
  // reject before invoking: threshold must be a plain decimal fraction
}

function isValidNgramThreshold($t) {
  return is_numeric($t) && (double)$t > 0.0 && (double)$t < 1.0;
}

When it happens

Trigger: `bin/search ngrams --threshold auto`, `--threshold 5%`, `--threshold ,5` (locale-typo), or shell quoting that injects stray characters.

Common situations: Passing percentages with a % suffix; locale/format confusion (comma decimal separator); quoting mistakes in scripts.

Related errors

• Specify either --reset or --threshold, not both.
• Specify either --reset or --threshold.
• Threshold must be greater than 0.0 and less than 1.0.
• Specify a device with --device.
• Specify a private key with --private-key.

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