phacility/phabricator · error · PhutilArgumentUsageException

Use "--lease" to specify a lease.

Error message

Use "--lease" to specify a lease.

What it means

A PhutilArgumentUsageException raised by `bin/drydock command` when the --lease flag is omitted. The workflow needs an existing lease to route the command through, so it immediately aborts with a usage hint before touching the database. It is purely a command-line usage error, not a state problem.

Source

Thrown at src/applications/drydock/management/DrydockManagementCommandWorkflow.php:28

      ->setArguments(
        array(
          array(
            'name' => 'lease',
            'param' => 'id',
            'help' => pht('Lease ID.'),
          ),
          array(
            'name' => 'argv',
            'wildcard' => true,
            'help' => pht('Command to execute.'),
          ),
        ));
  }

  public function execute(PhutilArgumentParser $args) {
    $lease_id = $args->getArg('lease');
    if (!$lease_id) {
      throw new PhutilArgumentUsageException(
        pht(
          'Use "--lease" to specify a lease.'));
    }

    $argv = $args->getArg('argv');
    if (!$argv) {
      throw new PhutilArgumentUsageException(
        pht(
          'Specify a command to run.'));
    }

    $lease = id(new DrydockLeaseQuery())
      ->setViewer($this->getViewer())
      ->withIDs(array($lease_id))
      ->executeOne();
    if (!$lease) {
      throw new Exception(
        pht(

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Add --lease <id> with the numeric ID of an acquired Drydock lease, e.g. `bin/drydock command --lease 42 -- ls /`.
2. If the lease ID comes from a script, guard the invocation so it fails clearly when the variable is empty.

Example fix

# before
bin/drydock command -- git status

# after
bin/drydock command --lease 42 -- git status

#!/bin/sh
[ -n "$LEASE_ID" ] || { echo 'LEASE_ID is empty; refusing to run drydock command' >&2; exit 2; }
exec bin/drydock command --lease "$LEASE_ID" -- "$@"

When it happens

Trigger: Running `bin/drydock command -- <cmd>` (or with only other flags) without --lease <id>. getArg('lease') is falsy and the workflow throws.

Common situations: Copy-pasting a command template and dropping the flag; assuming the workflow picks the most recent lease; scripting the CLI and an empty $LEASE_ID shell variable expands to nothing.

Related errors

• Specify a command to run.
• Unable to load lease with ID "%s"!
• Specify a resource type with "--type".
• Lease has already been released!
• Lease has already been destroyed!

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