phacility/phabricator · warning · PhutilArgumentUsageException

Specify which subscription to invoice with %s.

Error message

Specify which subscription to invoice with %s.

What it means

PhutilArgumentUsageException thrown by the phortune invoice management workflow (bin/phortune invoice) when execute() finds no --subscription argument. Phabricator management workflows use this exception type to abort with a usage message printed to stderr and a non-zero exit code; it signals caller misuse of the CLI, not a system fault. The required value is the PHID of the PhortuneSubscription to invoice.

Source

Thrown at src/applications/phortune/management/PhabricatorPhortuneManagementInvoiceWorkflow.php:55

            'name' => 'auto-range',
            'help' => pht('Automatically use the current billing period.'),
          ),
          array(
            'name' => 'force',
            'help' => pht(
              'Skip the prompt warning you that this operation is '.
              'potentially dangerous.'),
          ),
        ));
  }

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

    $subscription_phid = $args->getArg('subscription');
    if (!$subscription_phid) {
      throw new PhutilArgumentUsageException(
        pht(
          'Specify which subscription to invoice with %s.',
          '--subscription'));
    }

    $subscription = id(new PhortuneSubscriptionQuery())
      ->setViewer($viewer)
      ->withPHIDs(array($subscription_phid))
      ->needTriggers(true)
      ->executeOne();
    if (!$subscription) {
      throw new PhutilArgumentUsageException(
        pht(
          'Unable to load subscription with PHID "%s".',
          $subscription_phid));
    }

    $now = $args->getArg('now');

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Add --subscription with the subscription's PHID, copied from the subscription detail page URI/object in the Phortune UI.
2. If scripting, assert the PHID variable is non-empty (and looks like a PHID) before invoking the command.
3. Run `bin/phortune help invoice` to confirm the accepted argument names for your Phabricator version.

Example fix

# before
$ ./bin/phortune invoice

# after
$ ./bin/phortune invoice --subscription PHID-PSUB-abcdefghijklmnop

// Validate the invocation before shelling out.
function assert_invoice_argv(array $argv) {
  if (empty($argv['subscription']) || !preg_match('/^PHID-/', $argv['subscription'])) {
    fwrite(STDERR, "usage: phortune invoice --subscription <PHID> [--auto-range | --last E --next E] [--force]\n");
    exit(64); // EX_USAGE
  }
}

// PhutilArgumentUsageException prints its message and exits non-zero;
// when invoking from PHP, capture stderr + exit code instead of letting output vanish.
$err = exec(sprintf(
  '%s --subscription %s',
  escapeshellarg($bin),
  escapeshellarg($phid)),
  $output,
  $exit_code);
if ($exit_code !== 0) {
  throw new RuntimeException('phortune invoice failed: '.implode("\n", $output));
}

When it happens

Trigger: Running `bin/phortune invoice` with no flags; passing an empty --subscription (getArg('subscription') falsy, e.g. --subscription '' ); or scripting the command while the PHID variable is unset and expands to nothing.

Common situations: First-time use of the manual invoicing script during Phortune testing; cron/shell scripts interpolating an empty subscription variable; documentation or runbooks that omit the flag.

Related errors

• Specify a billing range with %s and %s, or use %s.
• When specifying %s or %s, you must specify both arguments to
• Use either %s or %s and %s to specify the billing range, but
• Unable to load subscription with PHID "%s".
• Unable to calculate %s, this subscription has not been sched

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