What causes "Unknown mode "%s". Valid modes are: %s." in phacility/phabricator?

Use exactly `--mode plain` (store chunks uncompressed) or `--mode compress` (store chunks compressed).

phacility/phabricator · warning · PhutilArgumentUsageException

Unknown mode "%s". Valid modes are: %s.

Error message

Unknown mode "%s". Valid modes are: %s.

What it means

The archive-logs workflow got a --mode value that is not in the valid set. Valid modes are exactly 'plain' and 'compress' (fused into a set before checking), so values like 'compressed', 'gzip', 'zstd', or 'PLAIN' fail here with the valid list in the message.

Source

Thrown at src/applications/harbormaster/management/HarbormasterManagementArchiveLogsWorkflow.php:45

  }

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

    $mode = $args->getArg('mode');
    if (!$mode) {
      throw new PhutilArgumentUsageException(
        pht('Choose an archival mode with --mode.'));
    }

    $valid_modes = array(
      'plain',
      'compress',
    );

    $valid_modes = array_fuse($valid_modes);
    if (empty($valid_modes[$mode])) {
      throw new PhutilArgumentUsageException(
        pht(
          'Unknown mode "%s". Valid modes are: %s.',
          $mode,
          implode(', ', $valid_modes)));
    }

    $log_table = new HarbormasterBuildLog();
    $logs = new LiskMigrationIterator($log_table);

    $show_details = $args->getArg('details');

    if ($show_details) {
      $total_old = 0;
      $total_new = 0;
    }

    foreach ($logs as $log) {
      echo tsprintf(

View on GitHub (pinned to 5720a38cfe)

Solutions

Use exactly `--mode plain` (store chunks uncompressed) or `--mode compress` (store chunks compressed).
Run with --help to confirm the accepted values on your version.

Example fix

# before
./bin/phabricator harbormaster archive-logs --mode compressed

# after
./bin/phabricaster archive-logs --mode compress

Defensive patterns

Strategy: validation

Validate before calling

$valid = array('plain', 'compress');
if (!in_array($mode, $valid, true)) {
  throw new PhutilArgumentUsageException(
    'Unknown mode. Valid modes are: '.implode(', ', $valid));
}

Type guard

function isValidArchiveMode($mode) {
  return in_array($mode, array('plain', 'compress'), true);
}

Try / catch

try {
  runArchiveLogs($args);
} catch (PhutilArgumentUsageException $e) {
  fwrite(STDERR, $e->getMessage()."\n");
  exit(64);
}

Prevention

Match flag values byte-for-byte against the list in the error message / --help output; the check is case-sensitive.
Pin automation to a documented set of CLI values and re-validate after Phabricator upgrades.

When it happens

Trigger: Passing --mode compressed, --mode gzip, --mode zlib, or any uppercase/misspelled variant; assuming the mode matches the log chunk encoding constant names instead of the CLI keywords; scripts written against different tooling.

Common situations: Guessing flag values instead of reading --help; migrating from a custom archival script whose mode names differ.

Related errors

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