What causes "Unable to load Herald rule with ID or monogram "%s"." in phacility/phabricator?

Confirm the rule exists and copy its exact monogram from the UI (H + digits), e.g. bin/herald rule --rule H42.

phacility/phabricator · error · PhutilArgumentUsageException

Unable to load Herald rule with ID or monogram "%s".

Error message

Unable to load Herald rule with ID or monogram "%s".

What it means

PhutilArgumentUsageException thrown by HeraldRuleManagementWorkflow when the --rule value (after stripping an 'H' monogram prefix) does not resolve to any HeraldRule via HeraldRuleQuery executed by the script's admin viewer. Either no rule with that ID exists, or the viewer cannot see it (though management workflows typically run with omnipotent/admin access, policy or a truly nonexistent ID still yields no result).

Source

Thrown at src/applications/herald/management/HeraldRuleManagementWorkflow.php:52

    $rule_name = $args->getArg('rule');
    if (!strlen($rule_name)) {
      throw new PhutilArgumentUsageException(
        pht('Specify a rule to edit with "--rule <id|monogram>".'));
    }

    if (preg_match('/^H\d+/', $rule_name)) {
      $rule_id = substr($rule_name, 1);
    } else {
      $rule_id = $rule_name;
    }

    $rule = id(new HeraldRuleQuery())
      ->setViewer($viewer)
      ->withIDs(array($rule_id))
      ->executeOne();
    if (!$rule) {
      throw new PhutilArgumentUsageException(
        pht(
          'Unable to load Herald rule with ID or monogram "%s".',
          $rule_name));
    }

    $is_disable = $args->getArg('disable');
    $is_enable = $args->getArg('enable');

    $xactions = array();

    if ($is_disable && $is_enable) {
      throw new PhutilArgumentUsageException(
        pht(
          'Specify "--enable" or "--disable", but not both.'));
    } else if ($is_disable || $is_enable) {
      $xactions[] = $rule->getApplicationTransactionTemplate()
        ->setTransactionType(HeraldRuleDisableTransaction::TRANSACTIONTYPE)
        ->setNewValue($is_disable);

View on GitHub (pinned to 5720a38cfe)

Solutions

Confirm the rule exists and copy its exact monogram from the UI (H + digits), e.g. bin/herald rule --rule H42.
If you only have a name, find the ID first from the rule list page (/herald/) or via 'H' monogram search, then re-run.
Check you are on the correct environment/database — IDs are per-install.
Remember names are not accepted: only 'H<id>' monograms or bare numeric IDs.

Example fix

# before
bin/herald rule --rule "Close on review" --disable

# after
bin/herald rule --rule H57 --disable

Defensive patterns

Strategy: validation

Validate before calling

// Resolve the rule exactly like the workflow, before editing
$rule_id = preg_match('/^H\d+/', $name) ? substr($name, 1) : $name;
$rule = id(new HeraldRuleQuery())
  ->setViewer($viewer)
  ->withIDs(array($rule_id))
  ->executeOne();
if (!$rule) {
  // friendly error listing available rule IDs, instead of an exception
}

Type guard

function isHeraldRuleMonogram($s) {
  return is_string($s) && preg_match('/^H\d+$/', $s) === 1;
}

Try / catch

try {
  (new HeraldRuleManagementWorkflow())->execute($args);
} catch (PhutilArgumentUsageException $ex) {
  if (strpos($ex->getMessage(), 'Unable to load Herald rule') !== false) {
    // list candidate rules (herald rule query / web UI) and re-prompt
  }
}

Prevention

Always pass the H-monogram copied from the rule URL; names are not accepted.
In automation, resolve the rule ID once and assert it exists before composing the edit command.

When it happens

Trigger: Running 'bin/herald rule --rule H9999' where rule 9999 does not exist; passing a name instead of an ID/monogram (e.g. --rule 'My Rule' — only '^H\d+' monograms and raw numeric IDs are handled); passing an ID from a different install/database; typos in the monogram.

Common situations: Operators copy a rule monogram from an old email/notification for a rule that was deleted; run the command against the wrong environment/database; or assume the tool accepts rule names. Note the workflow only special-cases monograms matching /^H\d+/ — anything else is fed raw to withIDs(), so 'T123' or 'herald-rule-3' never match.

Related errors

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