phacility/phabricator · warning · PhutilArgumentUsageException

Use %s to specify a build plan to run.

Error message

Use %s to specify a build plan to run.

What it means

Usage error from `harbormaster build`: after a valid buildable is resolved, a build plan must be chosen with --plan. The message explicitly names the missing flag.

Source

Thrown at src/applications/harbormaster/management/HarbormasterManagementBuildWorkflow.php:58

    $name = head($names);

    $buildable = id(new PhabricatorObjectQuery())
      ->setViewer($viewer)
      ->withNames($names)
      ->executeOne();
    if (!$buildable) {
      throw new PhutilArgumentUsageException(
        pht('No such buildable "%s"!', $name));
    }

    if (!($buildable instanceof HarbormasterBuildableInterface)) {
      throw new PhutilArgumentUsageException(
        pht('Object "%s" is not a buildable!', $name));
    }

    $plan_id = $args->getArg('plan');
    if (!$plan_id) {
      throw new PhutilArgumentUsageException(
        pht(
          'Use %s to specify a build plan to run.',
          '--plan'));
    }

    $plan = id(new HarbormasterBuildPlanQuery())
      ->setViewer($viewer)
      ->withIDs(array($plan_id))
      ->executeOne();
    if (!$plan) {
      throw new PhutilArgumentUsageException(
        pht('Build plan "%s" does not exist.', $plan_id));
    }

    if (!$plan->canRunManually()) {
      throw new PhutilArgumentUsageException(
        pht('This build plan can not be run manually.'));
    }

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Add the flag with a plan ID: `--plan 5` (numeric ID from the plan URI /harbormaster/plan/5/).
2. List plans in the UI (Build > Build Plans) to get the ID if unsure.

Example fix

# before
./bin/phabricator harbormaster build D123

# after
./bin/phabricator harbormaster build --plan 5 D123

if (empty($args['plan'])) {
  fwrite(STDERR, "Use --plan to specify a build plan to run.\n");
  exit(64);
}

try {
  runBuildWorkflow($args);
} catch (PhutilArgumentUsageException $e) {
  fwrite(STDERR, $e->getMessage()."\n");
  exit(64);
}

When it happens

Trigger: Running `harbormaster build D123` with no --plan; supplying the plan as a positional argument instead of a flag; a wrapper dropping the flag.

Common situations: First-time use; scripts adapted from the UI flow where the plan is chosen interactively.

Related errors

• Build plan "%s" does not exist.
• Choose an archival mode with --mode.
• Unknown mode "%s". Valid modes are: %s.
• Specify exactly one buildable object, by object name.
• No such buildable "%s"!

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