phacility/phabricator · warning · PhutilArgumentUsageException

Use --as <format> to select a target encoding format. Availa

Error message

Use --as <format> to select a target encoding format. Available formats are: %s.

What it means

The `./bin/files encode` workflow re-encodes stored files into a target format selected by --as <format-key>; the argument is required and this error is thrown when it is absent or empty. The message lists every registered format key (from PhabricatorFileStorageFormat::getAllFormats()) so the valid choices are visible.

Source

Thrown at src/applications/files/management/PhabricatorFilesManagementEncodeWorkflow.php:46

    $this
      ->setName('encode')
      ->setSynopsis(
        pht('Change the storage encoding of files.'))
      ->setArguments($arguments);
  }

  public function execute(PhutilArgumentParser $args) {
    $iterator = $this->buildIterator($args);

    $force = (bool)$args->getArg('force');

    $format_list = PhabricatorFileStorageFormat::getAllFormats();
    $format_list = array_keys($format_list);
    $format_list = implode(', ', $format_list);

    $format_key = $args->getArg('as');
    if (!strlen($format_key)) {
      throw new PhutilArgumentUsageException(
        pht(
          'Use --as <format> to select a target encoding format. Available '.
          'formats are: %s.',
          $format_list));
    }

    $format = PhabricatorFileStorageFormat::getFormat($format_key);
    if (!$format) {
      throw new PhutilArgumentUsageException(
        pht(
          'Storage format "%s" is not valid. Available formats are: %s.',
          $format_key,
          $format_list));
    }

    $key_name = $args->getArg('key');
    if (strlen($key_name)) {
      $format->selectMasterKey($key_name);

View on GitHub (pinned to 5720a38cfe)

Solutions

Add --as with a key from the listed formats: `./bin/files encode --as aes-256-cbc F123`
For encrypted targets without a default key, also pass --key <name>

Example fix

# before
./bin/files encode F123

# after
./bin/files encode --as aes-256-cbc --key prod-2024 F123

Defensive patterns

Strategy: validation

Validate before calling

# Script-side guard before running encode:
[ -n "$FORMAT_KEY" ] || { echo 'usage: encode.sh <format-key> <file>' >&2; exit 2; }
./bin/files encode --as "$FORMAT_KEY" "$FILE_MONO"

Prevention

Always pair encode invocations with an explicit --as from the documented format list
For encrypted targets, decide up front whether --key is needed based on the keyring default

When it happens

Trigger: Running `./bin/files encode F123` with no --as; passing --as "" (empty string).

Common situations: Assuming the workflow re-encrypts with the existing format or that a default exists; truncated command lines in documentation or scripts.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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