phacility/phabricator · warning · PhutilArgumentUsageException

%s argument '%s' is not a valid patch. Use '%s' to show patc

Error message

%s argument '%s' is not a valid patch. Use '%s' to show patch status.

What it means

`bin/storage upgrade --apply <key>` was given a patch key that does not exist in the compiled patch map (PhabricatorSQLPatchList::buildAllPatches()). Rather than silently doing nothing, the workflow refuses with this usage exception. The valid keys are exactly the ones `./bin/storage status` reports.

Source

Thrown at src/infrastructure/storage/management/workflow/PhabricatorStorageManagementUpgradeWorkflow.php:62

    if (!$this->isDryRun() && !$this->isForce()) {
      $console->writeOut(
        phutil_console_wrap(
          pht(
            'Before running storage upgrades, you should take down the '.
            'web interface and stop any running daemons (you can disable '.
            'this warning with %s).',
            '--force')));

      if (!phutil_console_confirm(pht('Are you ready to continue?'))) {
        $console->writeOut("%s\n", pht('Cancelled.'));
        return 1;
      }
    }

    $apply_only = $args->getArg('apply');
    if ($apply_only) {
      if (empty($patches[$apply_only])) {
        throw new PhutilArgumentUsageException(
          pht(
            "%s argument '%s' is not a valid patch. ".
            "Use '%s' to show patch status.",
            '--apply',
            $apply_only,
            './bin/storage status'));
      }
    }

    $no_quickstart = $args->getArg('no-quickstart');
    $init_only     = $args->getArg('init-only');
    $no_adjust     = $args->getArg('no-adjust');

    $apis = $this->getMasterAPIs();

    $this->upgradeSchemata($apis, $apply_only, $no_quickstart, $init_only);

    if ($apply_only || $init_only) {

View on GitHub (pinned to 5720a38cfe)

Solutions

1. List the real keys with `./bin/storage status` (or `ls resources/sql/patches/`) and copy the exact name.
2. Drop `--apply` entirely so upgrade applies every pending patch in dependency order.
3. If the patch should exist in your version, update the checkout (git pull, correct branch) and retry.

Example fix

# before
./bin/storage upgrade --apply db.audit.01

# after
./bin/storage status                 # copy the exact key
./bin/storage upgrade --apply db.audit.02

key=db.audit.02
if ! ./bin/storage status | grep -q "$key"; then
  echo "unknown patch key: $key" >&2
  exit 2
fi
./bin/storage upgrade --apply "$key"

When it happens

Trigger: `./bin/storage upgrade --apply <typo-or-wrong-version-key>` where the key is absent from the patch map of the current checkout (the empty($patches[$apply_only]) check trips).

Common situations: Typos in long dotted patch names; copy-pasting a patch name from a newer upstream diff into an older checkout; custom patch keys renamed in a fork; wrong branch checked out when running the command.

Related errors

• Storage on host "%s" has not been initialized yet. You must
• Some patches could not be applied: %s
• Specify the dumpfile to read with "--input", or use "--live"
• Specify namespace to rename from with %s.
• Specify namespace to rename to with %s.

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