What causes "Specify exactly one buildable object, by object name." in phacility/phabricator?

Provide exactly one name: `./bin/phabricator harbormaster build --plan 3 D123`.

phacility/phabricator · warning · PhutilArgumentUsageException

Specify exactly one buildable object, by object name.

Error message

Specify exactly one buildable object, by object name.

What it means

Usage error from `bin harbormaster build`: the command takes exactly one positional wildcard naming the object to build (a monogram like D123 or a PHID). Zero names or more than one name fails here before anything is queried.

Source

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

          array(
            'name' => 'background',
            'help' => pht(
              'Submit builds into the build queue normally instead of '.
              'running them in the foreground.'),
          ),
          array(
            'name'        => 'buildable',
            'wildcard'    => true,
          ),
        ));
  }

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

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

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

View on GitHub (pinned to 5720a38cfe)

Solutions

Provide exactly one name: `./bin/phabricator harbormaster build --plan 3 D123`.
For multiple objects, invoke the command once per object in a loop.
Quote arguments so globs do not expand unexpectedly.

Example fix

# before
./bin/phabricator harbormaster build --plan 3

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

Defensive patterns

Strategy: validation

Validate before calling

if (count($names) !== 1 || !reset($names)) {
  fwrite(STDERR, "Specify exactly one buildable object, by object name.\n");
  exit(64);
}

Try / catch

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

Prevention

Wrap harbormaster build invocations in a helper that validates argv (exactly one positional, --plan set) before exec.
Loop over objects one at a time in automation instead of passing them all at once.

When it happens

Trigger: Running `harbormaster build --plan 3` with no object argument; passing two objects ('D1 D2') hoping for a batch; a shell glob expanding to multiple or zero matches.

Common situations: Scripting the command and forgetting the wildcard; assuming the tool builds several objects in one invocation.

Related errors

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