phacility/phabricator · warning · PhutilArgumentUsageException

Choose which capabilities to unlock with "--view", "--edit",

Error message

Choose which capabilities to unlock with "--view", "--edit", or "--owner".

What it means

unlock needs at least one capability target: --view, --edit, or --owner, each taking a username. The three flags are loaded via loadUser(); if all resolve to null the workflow throws this usage exception before printing the policy table, because no change would be specified.

Source

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

    $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'));
    $owner_user = $this->loadUser($args->getArg('owner'));

    if (!$view_user && !$edit_user && !$owner_user) {
      throw new PhutilArgumentUsageException(
        pht(
          'Choose which capabilities to unlock with "--view", "--edit", '.
          'or "--owner".'));
    }

    $handle = id(new PhabricatorHandleQuery())
      ->setViewer($viewer)
      ->withPHIDs(array($object->getPHID()))
      ->executeOne();

    echo tsprintf(
      "<bg:blue>** %s **</bg> %s\n",
      pht('UNLOCKING'),
      pht('Unlocking: %s', $handle->getFullName()));

    $engine = PhabricatorUnlockEngine::newUnlockEngineForObject($object);

    $xactions = array();

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Add at least one flag with a username: ./bin/policy unlock T123 --edit alice (flags combine, e.g. --view alice --edit bob).
2. To only read policies, use ./bin/policy show T123.

Example fix

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

case " $* " in
  *' --view '*|*' --edit '*|*' --owner '*) ;;
  *) echo 'unlock needs --view, --edit, or --owner' >&2; exit 64 ;;
esac
exec ./bin/policy unlock "$@"

When it happens

Trigger: Running ./bin/policy unlock T123 with none of --view, --edit, or --owner supplied.

Common situations: Using unlock to inspect policies (show is the right command) and forgetting the capability flags in incident scripts.

Related errors

• Specify the name of an object to unlock.
• Specify the name of exactly one object to unlock.
• You must specify the path to a public keyfile with %s.
• You must specify the path to a pkcs8 keyfile with %s.
• You must specify the username of the account to recover.

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