phacility/phabricator · warning · PhutilArgumentUsageException

Threshold must be greater than 0.0 and less than 1.0.

Error message

Threshold must be greater than 0.0 and less than 1.0.

What it means

After the numeric cast, `bin/search ngrams --threshold` requires the value to be strictly inside the open interval (0, 1): values <= 0 or >= 1 throw. The threshold is the maximum fraction of documents an ngram may appear in before being treated as a common ngram (stopword), so 0 and 1 are rejected extremes. Note tables with fewer than 4096 documents ($min_documents) are skipped entirely.

Source

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

    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);

      if ($is_reset) {
        echo tsprintf(
          "%s\n",
          pht(
            'Resetting common ngrams for "%s".',

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Rescale percentages to fractions: 5% becomes 0.05
2. Pick a value strictly between 0 and 1, typically small (0.01-0.2) for large corpora
3. Remember engines with under 4096 documents are skipped regardless of threshold

Example fix

# before (intended "5 percent")
bin/search ngrams --threshold 5

# after
bin/search ngrams --threshold 0.05

if (!is_numeric($threshold) || (double)$threshold <= 0 || (double)$threshold >= 1) {
  // reject: threshold must be strictly between 0.0 and 1.0
}

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

When it happens

Trigger: `--threshold 1`, `--threshold 0`, `--threshold 1.5`, negative values, or percentage-style values like 5 (intending 5%).

Common situations: Assuming a 0-100 percent scale and passing 5 instead of 0.05; copying values from unrelated tooling; attempting 1.0 to 'include everything'.

Related errors

• Specify either --reset or --threshold, not both.
• Specify either --reset or --threshold.
• Specify a numeric threshold between 0 and 1.
• 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/df2e14fb3595aee7. Report an issue: GitHub.