phacility/phabricator · warning · PhutilArgumentUsageException

You must choose a device to --promote or --demote.

Error message

You must choose a device to --promote or --demote.

What it means

`bin/repository thaw` unfreezes clustered repository versions by promoting or demoting a specific device. The command requires exactly one of `--promote <device>` or `--demote <device>`; with neither, there is no thaw operation to perform and the workflow exits with this PhutilArgumentUsageException.

Source

Thrown at src/applications/repository/management/PhabricatorRepositoryManagementThawWorkflow.php:56

            'help' => pht(
              'Apply the promotion or demotion to all repositories hosted '.
              'on the device.'),
          ),
          array(
            'name' => 'repositories',
            'wildcard' => true,
          ),
        ));
  }

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

    $promote = $args->getArg('promote');
    $demote = $args->getArg('demote');

    if (!$promote && !$demote) {
      throw new PhutilArgumentUsageException(
        pht('You must choose a device to --promote or --demote.'));
    }

    if ($promote && $demote) {
      throw new PhutilArgumentUsageException(
        pht('Specify either --promote or --demote, but not both.'));
    }

    $target_name = nonempty($promote, $demote);

    $devices = id(new AlmanacDeviceQuery())
      ->setViewer($viewer)
      ->withNames(array($target_name))
      ->execute();
    if (!$devices) {
      $service = id(new AlmanacServiceQuery())
        ->setViewer($viewer)
        ->withNames(array($target_name))

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Pass a target: `./bin/repository thaw --promote <device>` to make a device's version authoritative, or `--demote <device>` to discard its version.
2. Quote script variables and check they are non-empty before building the command (`: "${DEVICE:?device required}"`).
3. Read `./bin/repository thaw --help` and the clustering documentation — thawing is for resolving frozen/demoted cluster states.

Example fix

# before
./bin/repository thaw
# Usage exception: You must choose a device to --promote or --demote.

# after
./bin/repository thaw --promote repo-host-01

# Require a promote/demote target with a non-empty device name
: "${DEVICE:?thaw requires a device via --promote or --demote}"
./bin/repository thaw ${OP:+--$OP "$DEVICE"}   # OP is 'promote' or 'demote'

When it happens

Trigger: Bare `./bin/repository thaw` invocation, or one with only auxiliary flags (e.g. `--enqueue`) and no `--promote`/`--demote` target.

Common situations: Operators unfamiliar with cluster unfreezing exploring the command; scripts where the device name variable expanded to empty so the flag was omitted.

Related errors

• Specify either --promote or --demote, but not both.
• No device or service named "%s" exists.
• You can not "--promote" an entire service ("%s"). Only a sin
• Service "%s" is not bound to any devices.
• Specify which subscription to invoice with %s.

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