phacility/phabricator · warning · PhutilArgumentUsageException

Specify the name of an object to unlock.

Error message

Specify the name of an object to unlock.

What it means

bin/policy unlock rewrites an object's policies to rescue objects nobody can reach. It requires exactly one object name; an empty `objects` argument throws this usage exception before anything is loaded.

Source

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

          array(
            'name' => 'owner',
            'param' => 'username',
            '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 on GitHub (pinned to 5720a38cfe)

Solutions

1. Pass one object name plus a capability flag: ./bin/policy unlock T123 --edit alice
2. If you only want to inspect policies, use ./bin/policy show T123 instead.

Example fix

# before
./bin/policy unlock
# after
./bin/policy unlock T123 --edit alice

#!/bin/sh
[ "$#" -ge 1 ] || { echo 'usage: bin/policy unlock <object> --view|--edit|--owner <user>' >&2; exit 64; }
exec ./bin/policy unlock "$@"

When it happens

Trigger: Running ./bin/policy unlock with no arguments.

Common situations: Exploring the rescue tooling and forgetting the argument in runbooks or incident scripts.

Related errors

• Specify the name of an object to show policy information for
• Specify the name of exactly one object to unlock.
• Choose which capabilities to unlock with "--view", "--edit",
• You must specify the path to a public keyfile with %s.
• You must specify the path to a pkcs8 keyfile with %s.

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