phacility/phabricator · warning · PhutilArgumentUsageException

Specify exactly one buildable, by object name.

Error message

Specify exactly one buildable, by object name.

What it means

Usage exception from 'bin/harbormaster update'. This workflow advances the state machine of exactly one buildable, so the wildcard 'buildable' argument must contain exactly one object name (monogram or PHID). Zero names or more than one name fails this count check before any query runs.

Source

Thrown at src/applications/harbormaster/management/HarbormasterManagementUpdateWorkflow.php:44

            'help' => pht(
              'If updating generates tasks, queue them for the daemons '.
              'instead of executing them in this process.'),
          ),
          array(
            'name'        => 'buildable',
            'wildcard'    => true,
          ),
        ));
  }

  public function execute(PhutilArgumentParser $args) {
    $viewer = $this->getViewer();

    $force_update = $args->getArg('force');

    $names = $args->getArg('buildable');
    if (count($names) != 1) {
      throw new PhutilArgumentUsageException(
        pht('Specify exactly one buildable, by object name.'));
    }

    $buildable = id(new PhabricatorObjectQuery())
      ->setViewer($viewer)
      ->withNames($names)
      ->executeOne();

    if (!$buildable) {
      throw new PhutilArgumentUsageException(
        pht('No such buildable "%s"!', head($names)));
    }

    if (!($buildable instanceof HarbormasterBuildable)) {
      throw new PhutilArgumentUsageException(
        pht('Object "%s" is not a Harbormaster Buildable!', head($names)));
    }

View on GitHub (pinned to 5720a38cfe)

Solutions

  1. Pass exactly one name: 'bin/harbormaster update B123'
  2. For several buildables, loop the command once per name
  3. In scripts, abort early when the name variable is empty instead of running the command

Example fix

# before
$ bin/harbormaster update
$ bin/harbormaster update B1 B2
# after
$ for b in B1 B2; do bin/harbormaster update "$b"; done
Defensive patterns

Strategy: validation

Validate before calling

# shell wrapper: exactly one buildable name
if [ $# -ne 1 ]; then
  echo 'error: exactly one buildable name required' >&2
  exit 1
fi

Prevention

When it happens

Trigger: Running 'bin/harbormaster update' with no buildable argument, or 'bin/harbormaster update B1 B2' with two names.

Common situations: An unset variable in automation expands to zero arguments; looping over names but passing them all on one command line instead of one per invocation.

Related errors

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