phacility/phabricator · warning · PhutilArgumentUsageException

Specify one or more users to send a message to with "--to" a

Error message

Specify one or more users to send a message to with "--to" and/or "--cc".

What it means

`bin/mail send-test` requires at least one recipient and rejects the invocation when both `--to` and `--cc` are empty. The recipient pool is built exclusively from these two repeatable flags, so with neither present there is nobody to deliver to and the workflow throws PhutilArgumentUsageException before constructing the mail.

Source

Thrown at src/applications/metamta/management/PhabricatorMailManagementSendTestWorkflow.php:107

    $from = $args->getArg('from');
    if ($from) {
      $user = id(new PhabricatorPeopleQuery())
        ->setViewer($viewer)
        ->withUsernames(array($from))
        ->executeOne();
      if (!$user) {
        throw new PhutilArgumentUsageException(
          pht("No such user '%s' exists.", $from));
      }
      $from = $user;
    }

    $tos = $args->getArg('to');
    $ccs = $args->getArg('cc');

    if (!$tos && !$ccs) {
      throw new PhutilArgumentUsageException(
        pht(
          'Specify one or more users to send a message to with "--to" and/or '.
          '"--cc".'));
    }

    $names = array_merge($tos, $ccs);
    $users = id(new PhabricatorPeopleQuery())
      ->setViewer($viewer)
      ->withUsernames($names)
      ->execute();
    $users = mpull($users, null, 'getUsername');

    $raw_tos = array();
    foreach ($tos as $key => $username) {
      // If the recipient has an "@" in any noninitial position, treat this as
      // a raw email address.
      if (preg_match('/.@/', $username)) {
        $raw_tos[] = $username;

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Add at least one recipient: `--to <username>` or `--cc <username>` (both repeatable).
2. To reach an address outside Phabricator, pass a raw email (contains '@') such as `--to user@example.com`.
3. In scripts, assert the recipient array is non-empty before shelling out to the workflow.

Example fix

// before
$ bin/mail send-test --subject hi
// Exception: Specify one or more users to send a message to with "--to" and/or "--cc".

// after
$ bin/mail send-test --subject hi --to alincoln

// Assert recipients before shelling out:
if (empty($to_list) && empty($cc_list)) {
  fwrite(STDERR, "send-test requires at least one --to or --cc recipient.\n");
  exit(1);
}

When it happens

Trigger: Invoking send-test with only mailer/subject/body flags; a scripted call whose recipient variable expanded to an empty list; passing --to with an empty string value.

Common situations: Mailer connectivity tests where the author focuses on --mailer and forgets recipients; automation templates that forgot the recipient flags.

Related errors

• Message type "%s" is unknown, supported message types are: %
• Use the '%s' flag to specify one or more messages to show.
• 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/93752f434dc61f48. Report an issue: GitHub.