What causes "Specify the name of exactly one object to unlock." in phacility/phabricator?

Run the command once per object with exactly one name, then add the --view/--edit/--owner flags.

phacility/phabricator · warning · PhutilArgumentUsageException

Specify the name of exactly one object to unlock.

Error message

Specify the name of exactly one object to unlock.

What it means

Usage guard in the policy 'unlock' CLI workflow: fires when more than one object name was passed. Unlocking (resetting the policy/owner of) an object is inherently single-object, so the arity check rejects extra names before any object lookup or modification happens.

Solutions

Run the command once per object with exactly one name, then add the --view/--edit/--owner flags.

Example fix

# before
./bin/policy unlock T1 T2 --edit alice
# after
./bin/policy unlock T1 --edit alice && ./bin/policy unlock T2 --edit alice

Defensive patterns

Strategy: validation

Validate before calling

#!/bin/sh
objs="$1"; shift
[ -n "$objs" ] && [ $# -eq 0 ] || { echo 'exactly one object name allowed' >&2; exit 64; }
exec ./bin/policy unlock "$objs" "$@"

Prevention

Batch rescues must loop: one invocation per object.
Avoid unquoted globs that expand to several monograms.

When it happens

Trigger: Running ./bin/policy unlock T1 T2, or a shell glob expanding to several monograms.

Common situations: Batch rescue attempts that must be split into one call per object.

Related errors

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

Appendix: source

Thrown at src/applications/policy/management/PhabricatorPolicyManagementUnlockWorkflow.php:58

            'help' => pht(
              'Change the owner of an object to the specified user.'),
          ),
          array(
            'name' => 'objects',
            'wildcard' => true,
          ),
        ));
  }

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

    $object_names = $args->getArg('objects');
    if (!$object_names) {
      throw new PhutilArgumentUsageException(
        pht('Specify the name of an object to unlock.'));
    } else if (count($object_names) > 1) {
      throw new PhutilArgumentUsageException(
        pht('Specify the name of exactly one object to unlock.'));
    }

    $object_name = head($object_names);

    $object = id(new PhabricatorObjectQuery())
      ->setViewer($viewer)
      ->withNames(array($object_name))
      ->executeOne();
    if (!$object) {
      throw new PhutilArgumentUsageException(
        pht(
          'Unable to find any object with the specified name ("%s").',
          $object_name));
    }

    $view_user = $this->loadUser($args->getArg('view'));
    $edit_user = $this->loadUser($args->getArg('edit'));

View on GitHub (pinned to 5720a38cfe)