phacility/phabricator · warning · PhutilArgumentUsageException

Period specified with --days must be at least 1.

Error message

Period specified with --days must be at least 1.

What it means

`bin/mail volume` reports mail volume over a window ending now; `--days` is cast to int and must be >= 1, otherwise PhutilArgumentUsageException. Because the cast happens first, non-numeric strings and empty values become 0 and also fail. The value feeds phutil_units("N days in seconds"), which is why 0/negative is rejected.

Source

Thrown at src/applications/metamta/management/PhabricatorMailManagementVolumeWorkflow.php:31

      ->setArguments(
        array(
          array(
            'name'    => 'days',
            'param'   => 'days',
            'default' => 30,
            'help'    => pht(
              'Number of days back (default 30).'),
          ),
        ));
  }

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

    $days = (int)$args->getArg('days');
    if ($days < 1) {
      throw new PhutilArgumentUsageException(
        pht(
          'Period specified with --days must be at least 1.'));
    }

    $duration = phutil_units("{$days} days in seconds");

    $since = (PhabricatorTime::getNow() - $duration);
    $until = PhabricatorTime::getNow();

    $mails = id(new PhabricatorMetaMTAMailQuery())
      ->setViewer($viewer)
      ->withDateCreatedBetween($since, $until)
      ->execute();

    $unfiltered = array();
    $delivered = array();

    foreach ($mails as $mail) {

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Use a positive integer: `bin/mail volume --days 30`.
2. For a single day, pass `--days 1`.
3. Validate/cast the value to a positive int in scripts before invoking.

Example fix

// before
$ bin/mail volume --days abc
// Exception: Period specified with --days must be at least 1.

// after
$ bin/mail volume --days 30

// Mirror the workflow's cast-then-compare rule:
function is_valid_volume_days($value) {
  return (int)$value >= 1;
}
if (!is_valid_volume_days($days)) {
  fwrite(STDERR, "--days must be an integer >= 1.\n");
  exit(1);
}

When it happens

Trigger: `--days 0`, `--days -7`, `--days abc`, or `--days ''` (all cast to an int < 1).

Common situations: Automation passing an unset variable as the days value; operators assuming 0 means 'today' (it does not — use --days 1).

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.
• Use the '%s' flag to specify one or more messages to show.
• Argument "%s" is not a valid message ID.

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