phacility/phabricator · error · PhutilArgumentUsageException

Flag "--overwrite" has no effect when outputting to stdout.

Error message

Flag "--overwrite" has no effect when outputting to stdout.

What it means

The export workflow rejects combining --overwrite with '--output -'. Overwrite semantics only apply to files; stdout cannot be overwritten, so the flag is meaningless there. Phabricator throws this usage exception rather than silently ignoring the flag, to keep script behavior explicit.

Source

Thrown at src/applications/transactions/bulk/management/PhabricatorBulkManagementExportWorkflow.php:94

    $is_overwrite = $args->getArg('overwrite');
    $output_path = $args->getArg('output');

    if (!strlen($output_path)) {
      throw new PhutilArgumentUsageException(
        pht(
          'Use "--output <path>" to specify an output file, or "--output -" '.
          'to print to stdout.'));
    }

    if ($output_path === '-') {
      $is_stdout = true;
    } else {
      $is_stdout = false;
    }

    if ($is_stdout && $is_overwrite) {
      throw new PhutilArgumentUsageException(
        pht(
          'Flag "--overwrite" has no effect when outputting to stdout.'));
    }

    if (!$is_overwrite) {
      if (!$is_stdout && Filesystem::pathExists($output_path)) {
        throw new PhutilArgumentUsageException(
          pht(
            'Output path already exists. Use "--overwrite" to overwrite '.
            'it.'));
      }
    }

    // If we have more than one query, execute the queries to figure out which
    // results they hit, then build a synthetic query for all those results
    // using the IDs.
    if (count($queries) > 1) {
      $saved_query = $this->newUnionQuery($engine, $queries);

View on GitHub (pinned to 5720a38cfe)

Solutions

1. Remove --overwrite from the command when using --output -.
2. Keep a file destination (--output <path>) if you actually want overwrite behavior.
3. Build the flag list programmatically so --overwrite is only appended for file destinations.

Example fix

# before
bin/bulk export --query all --output - --overwrite
# after
bin/bulk export --query all --output -

# only add --overwrite for file destinations
flags=(--query "$QUERY" --output "$DEST")
if [[ "$DEST" != '-' && "$ALLOW_OVERWRITE" == 1 ]]; then
  flags+=(--overwrite)
fi
bin/bulk export "${flags[@]}"

Catch PhutilArgumentUsageException in PHP tooling and treat the message text as user-facing guidance: print it verbatim and exit with a usage error code.

When it happens

Trigger: Running `bin/bulk export ... --output - --overwrite`. $is_overwrite is true from --overwrite, $is_stdout is true when --output equals '-', and that exact combination throws before any query runs.

Common situations: Scripts templated from a file-export command where --overwrite was already present; users switching the destination from a file to stdout by editing only the path value.

Related errors

• Flags "--all-repositories" and "--repository" are not compat
• Flags "--all-identities" and "--raw" are not compatible.
• Specify a commit or repository to reparse, not both: All fro
• Choosing steps with "--importing" conflicts with flags which
• You must use "--all" if you specify "--min-date".

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