rectorphp/rector · error · RectorRuleNameAmbiguousException

Short rule name "%s" is ambiguous. Specify the full rule nam

Error message

Short rule name "%s" is ambiguous. Specify the full rule name:
- %s

What it means

OnlyRuleResolver backs the --only option: it first tries an exact class match, then suffix (short-name) matching over the rules registered in your config. If a short name like SomeRector matches more than one registered rule class, it throws RectorRuleNameAmbiguousException listing every candidate so you can disambiguate. This is a deliberate usability guard, not a corruption error.

Source

Thrown at src/Configuration/OnlyRuleResolver.php:55

            if (get_class($rector) === $rule) {
                return $rule;
            }
        }
        // allow short rule names if there are not duplicates
        $matching = [];
        foreach ($this->rectors as $rector) {
            if (substr_compare(get_class($rector), '\\' . $rule, -strlen('\\' . $rule)) === 0) {
                $matching[] = get_class($rector);
            }
        }
        $matching = array_unique($matching);
        if (count($matching) === 1) {
            return $matching[0];
        }
        if (count($matching) > 1) {
            sort($matching);
            $message = sprintf('Short rule name "%s" is ambiguous. Specify the full rule name:' . \PHP_EOL . '- ' . implode(\PHP_EOL . '- ', $matching), $rule);
            throw new RectorRuleNameAmbiguousException($message);
        }
        if (strpos($rule, '\\') === \false) {
            // the shell has eaten unescaped backslashes, e.g. --only=\Rector\Some\Rule
            $flattenMatching = [];
            foreach ($this->rectors as $rector) {
                if (str_replace('\\', '', get_class($rector)) === $rule) {
                    $flattenMatching[] = get_class($rector);
                }
            }
            $flattenMatching = array_unique($flattenMatching);
            if (count($flattenMatching) === 1) {
                return $flattenMatching[0];
            }
            $message = sprintf('Rule "%s" was not found.%sThe rule has no namespace. Make sure to escape the backslashes, and add quotes around the rule name: --only="My\Rector\Rule"', $rule, \PHP_EOL);
        } else {
            // the rule class exists, it is just missing in the config
            if ($this->isRectorRuleClass($rule)) {
                throw new RectorRuleNotFoundException($this->createUnregisteredMessage($rule));

View on GitHub (pinned to 408fcb0ff1)

Solutions

1. Re-run with the fully qualified class name from the candidate list: --only="App\Rules\SomeRector"
2. Copy the exact class string from the exception output (it is sorted, one candidate per line) and quote it in the shell

Example fix

# before: ambiguous short name
vendor/bin/rector process src --only=RenameVariableRector

# after: pick one candidate from the listed classes
vendor/bin/rector process src --only="Rector\Renaming\Rector\Variable\RenameVariableRector"

// prefer exact FQCNs; if you must accept short names, resolve them first
$rule = 'App\Rules\SomeRector'; // full class, unambiguous by construction
// shell: vendor/bin/rector process src --only="App\Rules\SomeRector"

catch \Rector\Exception\Configuration\RectorRuleNameAmbiguousException, parse the candidate list from the message, and if exactly one candidate is desired re-invoke with that FQCN; otherwise surface the list to the user.

When it happens

Trigger: Running vendor/bin/rector process src --only=SomeRector when two registered rule classes end with \SomeRector (e.g. Rector\A\SomeRector and App\Rules\SomeRector both registered via withRules() or sets).

Common situations: Projects registering many sets where identically named rules from different namespaces coexist; typos intended as full names that accidentally suffix-match several rules.

Related errors

• Rule "%s" exists, but is not registered in your Rector confi
• Rule "%s" was not found.%sThe rule has no namespace. Make su
• Rule "%s" was not found.%sMake sure it is registered in your
• [parallel] Main script was not found
• Rector name cannot be empty

AI-assisted analysis of rectorphp/rector@408fcb0ff1 (2026-08-21). Data as JSON: /api/errors/3a4da33f25150fed. Report an issue: GitHub.