phacility/phabricator · warning · PhutilArgumentUsageException

The "--overwrite" flag can only be used alongside "--output"

Error message

The "--overwrite" flag can only be used alongside "--output".

What it means

Thrown by `bin/storage renamespace` when `--overwrite` is passed without `--output`. Without `--output` the workflow streams the renamed dump to stdout, where an overwrite flag has no meaning, so the tool rejects the combination. This is a PhutilArgumentUsageException: nothing runs.

Source

Thrown at src/infrastructure/storage/management/workflow/PhabricatorStorageManagementRenamespaceWorkflow.php:92

          '--from'));
    }

    $to = $args->getArg('to');
    if (!strlen($to)) {
      throw new PhutilArgumentUsageException(
        pht(
          'Specify namespace to rename to with %s.',
          '--to'));
    }


    $output_file = $args->getArg('output');
    $is_overwrite = $args->getArg('overwrite');
    $is_compress = $args->getArg('compress');

    if ($is_overwrite) {
      if ($output_file === null) {
        throw new PhutilArgumentUsageException(
          pht(
            'The "--overwrite" flag can only be used alongside "--output".'));
      }
    }

    if ($output_file !== null) {
      if (Filesystem::pathExists($output_file)) {
        if (!$is_overwrite) {
          throw new PhutilArgumentUsageException(
            pht(
              'Output file "%s" already exists. Use "--overwrite" '.
              'to overwrite.',
              $output_file));
        }
      }
    }

    if ($is_live) {

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Add `--output <file>`, since an overwrite target is what you intended.
2. Or remove `--overwrite` when piping the result to stdout or into another program.

Example fix

# before
./bin/storage renamespace --input d.sql --from a --to b --overwrite

# after
./bin/storage renamespace --input d.sql --from a --to b --output /tmp/out.sql --overwrite

if [ -n "$OVERWRITE" ] && [ -z "$OUT" ]; then
  echo 'error: --overwrite requires --output' >&2
  exit 2
fi

When it happens

Trigger: `./bin/storage renamespace ... --overwrite` with no `--output` file, leaving $is_overwrite true and $output_file === null.

Common situations: Assembling flags in a script and removing the --output line while debugging; copy-pasting flag sets between two commands; intending to overwrite an earlier file but forgetting the path.

Related errors

• Specify the dumpfile to read with "--input", or use "--live"
• Output file "%s" already exists. Use "--overwrite" to overwr
• Specify namespace to rename from with %s.
• Specify namespace to rename to with %s.
• Specify a device with --device.

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