phacility/phabricator · warning · PhutilArgumentUsageException

Use the '%s' flag to specify one or more messages to show.

Error message

Use the '%s' flag to specify one or more messages to show.

What it means

`bin/mail show-inbound` requires at least one message ID via the repeatable `--id` flag; with no IDs it has nothing to load from PhabricatorMetaMTAReceivedMail and throws PhutilArgumentUsageException immediately. Inbound message IDs are the numeric IDs of received-mail records.

Source

Thrown at src/applications/metamta/management/PhabricatorMailManagementShowInboundWorkflow.php:28

      ->setExamples(
        '**show-inbound** --id 1 --id 2')
      ->setArguments(
        array(
          array(
            'name'    => 'id',
            'param'   => 'id',
            'help'    => pht('Show details about inbound mail with given ID.'),
            'repeat'  => true,
          ),
        ));
  }

  public function execute(PhutilArgumentParser $args) {
    $console = PhutilConsole::getConsole();

    $ids = $args->getArg('id');
    if (!$ids) {
      throw new PhutilArgumentUsageException(
        pht(
          "Use the '%s' flag to specify one or more messages to show.",
          '--id'));
    }

    $messages = id(new PhabricatorMetaMTAReceivedMail())->loadAllWhere(
      'id IN (%Ld)',
      $ids);

    if ($ids) {
      $ids = array_fuse($ids);
      $missing = array_diff_key($ids, $messages);
      if ($missing) {
        throw new PhutilArgumentUsageException(
          pht(
            'Some specified messages do not exist: %s',
            implode(', ', array_keys($missing))));
      }

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Pass one or more IDs: `bin/mail show-inbound --id 123 --id 456`.
2. Find IDs in the web UI under the received-mail (MetaMTAReceivedMail) list or from `bin/mail show-inbound` on a known recent message.
3. In scripts, assert the ID list is non-empty before invoking.

Example fix

// before
$ bin/mail show-inbound
// Exception: Use the '--id' flag to specify one or more messages to show.

// after
$ bin/mail show-inbound --id 123

if (empty($ids)) {
  fwrite(STDERR, "show-inbound requires one or more --id values.\n");
  exit(1);
}

When it happens

Trigger: Running show-inbound with no arguments; passing IDs via an unrecognized flag name; a script whose ID list expanded empty.

Common situations: Exploratory runs to 'see what the command does'; forgetting that this tool is per-ID rather than a listing tool.

Related errors

• Message type "%s" is unknown, supported message types are: %
• Specify one or more users to send a message to with "--to" a
• Use the '%s' flag to specify one or more messages to show.
• Argument "%s" is not a valid message ID.
• No such user '%s' exists.

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