What causes "Specify a user to notify with "--user"." in phacility/phabricator?

Run with --user , e.g. ./bin/aphlict notify --user admin --message 'hello'.

phacility/phabricator · error · PhutilArgumentUsageException

Specify a user to notify with "--user".

Error message

Specify a user to notify with "--user".

What it means

Usage error from the Aphlict notify management workflow: the required --user argument was missing or empty. The check is strlen($username) on $args->getArg('user') before any user lookup, so Phabricator rejects the invocation immediately.

Source

Thrown at src/applications/aphlict/management/PhabricatorAphlictManagementNotifyWorkflow.php:30

          array(
            'name' => 'user',
            'param' => 'username',
            'help' => pht('User to notify.'),
          ),
          array(
            'name' => 'message',
            'param' => 'text',
            'help' => pht('Message to send.'),
          ),
        ));
  }

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

    $username = $args->getArg('user');
    if (!strlen($username)) {
      throw new PhutilArgumentUsageException(
        pht(
          'Specify a user to notify with "--user".'));
    }

    $user = id(new PhabricatorPeopleQuery())
      ->setViewer($viewer)
      ->withUsernames(array($username))
      ->executeOne();

    if (!$user) {
      throw new PhutilArgumentUsageException(
        pht(
          'No user with username "%s" exists.',
          $username));
    }

    $message = $args->getArg('message');
    if (!strlen($message)) {

View on GitHub (pinned to 5720a38cfe)

Solutions

Run with --user <username>, e.g. ./bin/aphlict notify --user admin --message 'hello'.
In scripts, assert the variable is non-empty before invoking.
Confirm the username is the account's exact username (case-sensitive lookup follows).

Defensive patterns

Strategy: validation

Validate before calling

// Shell guard:
// [ -n "$NOTIFY_USER" ] || { echo 'error: --user is required' >&2; exit 1; }
// PHP guard when composing the invocation:
if (!strlen($username)) {
  throw new Exception('Notify requires --user <username>.');
}

Try / catch

try {
  // execute notify workflow
} catch (PhutilArgumentUsageException $ex) {
  // Usage error: print message, exit 2; do not retry.
  fwrite(STDERR, $ex->getMessage()."\n");
  exit(2);
}

Prevention

Template notify commands with both flags always present: --user X --message Y.
Fail scripts early on empty variables instead of letting the CLI catch them.
Keep a one-line example in runbooks so operators copy a complete invocation.

When it happens

Trigger: Running ./bin/aphlict notify (or the notify workflow) without --user, or with --user '' because a shell variable expanded empty.

Common situations: Smoke-testing the notification server and forgetting the flag; scripts where $USERNAME_ARG is unset under set -u-less bash.

Related errors

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