phacility/phabricator · error · PhutilArgumentUsageException

You can not "--promote" an entire service ("%s"). Only a sin

Error message

You can not "--promote" an entire service ("%s"). Only a single device may be promoted.

What it means

thaw can `--demote` an entire Almanac service (discarding every version in it at once), but `--promote` must name a single device: promoting makes one device's version authoritative, which is meaningless for a multi-device aggregate. When the resolved target is a service and `--promote` was used, the workflow rejects it with this PhutilArgumentUsageException.

Source

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

    $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))
        ->executeOne();

      if (!$service) {
        throw new PhutilArgumentUsageException(
          pht('No device or service named "%s" exists.', $target_name));
      }

      if ($promote) {
        throw new PhutilArgumentUsageException(
          pht(
            'You can not "--promote" an entire service ("%s"). Only a single '.
            'device may be promoted.',
            $target_name));
      }

      $bindings = id(new AlmanacBindingQuery())
        ->setViewer($viewer)
        ->withServicePHIDs(array($service->getPHID()))
        ->execute();
      if (!$bindings) {
        throw new PhutilArgumentUsageException(
          pht(
            'Service "%s" is not bound to any devices.',
            $target_name));
      }

      $interfaces = id(new AlmanacInterfaceQuery())

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Promote a specific device bound to that service instead: list the service's bindings/devices in the Almanac console and pass that device's name.
2. If you truly meant to discard versions wholesale, that is `--demote <service>`, not promote.

Example fix

# before
./bin/repository thaw --promote repo-cluster   # Almanac service name
# Usage exception: You can not "--promote" an entire service ("repo-cluster")...

# after: promote one device bound to the service
./bin/repository thaw --promote repo-host-01

# Ensure the promote target is a device, not a service
name='repo-host-01'
services=$(mysql -N -B phabricator_almanac -e \
  "SELECT COUNT(*) FROM almanac_service WHERE name = '$name'")
[ "$services" -eq 0 ] || { echo "cannot --promote a service; promote one of its devices" >&2; exit 1; }
./bin/repository thaw --promote "$name"

When it happens

Trigger: Running `./bin/repository thaw --promote <service-name>` where the name resolves to an Almanac service rather than a device — e.g. promoting the repository cluster service itself.

Common situations: Operators pasting the service name (the object most visible in the cluster UI) instead of one of its bound devices during an unfreeze incident.

Related errors

• No device or service named "%s" exists.
• Service "%s" is not bound to any devices.
• You must choose a device to --promote or --demote.
• Specify either --promote or --demote, but not both.
• No repository service "%s" exists.

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