{"record":{"id":"3a4da33f25150fed","repo":"rectorphp/rector","slug":"short-rule-name-s-is-ambiguous-specify-the-ful","errorCode":null,"errorMessage":"Short rule name \"%s\" is ambiguous. Specify the full rule name:\n- %s","messagePattern":"Short rule name \"(.+?)\" is ambiguous\\. Specify the full rule name:\n- (.+?)","errorType":"exception","errorClass":"RectorRuleNameAmbiguousException","httpStatus":null,"severity":"error","filePath":"src/Configuration/OnlyRuleResolver.php","lineNumber":55,"sourceCode":"            if (get_class($rector) === $rule) {\n                return $rule;\n            }\n        }\n        // allow short rule names if there are not duplicates\n        $matching = [];\n        foreach ($this->rectors as $rector) {\n            if (substr_compare(get_class($rector), '\\\\' . $rule, -strlen('\\\\' . $rule)) === 0) {\n                $matching[] = get_class($rector);\n            }\n        }\n        $matching = array_unique($matching);\n        if (count($matching) === 1) {\n            return $matching[0];\n        }\n        if (count($matching) > 1) {\n            sort($matching);\n            $message = sprintf('Short rule name \"%s\" is ambiguous. Specify the full rule name:' . \\PHP_EOL . '- ' . implode(\\PHP_EOL . '- ', $matching), $rule);\n            throw new RectorRuleNameAmbiguousException($message);\n        }\n        if (strpos($rule, '\\\\') === \\false) {\n            // the shell has eaten unescaped backslashes, e.g. --only=\\Rector\\Some\\Rule\n            $flattenMatching = [];\n            foreach ($this->rectors as $rector) {\n                if (str_replace('\\\\', '', get_class($rector)) === $rule) {\n                    $flattenMatching[] = get_class($rector);\n                }\n            }\n            $flattenMatching = array_unique($flattenMatching);\n            if (count($flattenMatching) === 1) {\n                return $flattenMatching[0];\n            }\n            $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);\n        } else {\n            // the rule class exists, it is just missing in the config\n            if ($this->isRectorRuleClass($rule)) {\n                throw new RectorRuleNotFoundException($this->createUnregisteredMessage($rule));","sourceCodeStart":37,"sourceCodeEnd":73,"githubUrl":"https://github.com/rectorphp/rector/blob/408fcb0ff1833e3d26cbc9b04c23a77565814a16/src/Configuration/OnlyRuleResolver.php#L37-L73","documentation":"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.","triggerScenarios":"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).","commonSituations":"Projects registering many sets where identically named rules from different namespaces coexist; typos intended as full names that accidentally suffix-match several rules.","solutions":["Re-run with the fully qualified class name from the candidate list: --only=\"App\\Rules\\SomeRector\"","Copy the exact class string from the exception output (it is sorted, one candidate per line) and quote it in the shell"],"exampleFix":"# before: ambiguous short name\nvendor/bin/rector process src --only=RenameVariableRector\n\n# after: pick one candidate from the listed classes\nvendor/bin/rector process src --only=\"Rector\\Renaming\\Rector\\Variable\\RenameVariableRector\"","handlingStrategy":"validation","validationCode":"// prefer exact FQCNs; if you must accept short names, resolve them first\n$rule = 'App\\Rules\\SomeRector'; // full class, unambiguous by construction\n// shell: vendor/bin/rector process src --only=\"App\\Rules\\SomeRector\"","typeGuard":null,"tryCatchPattern":"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.","preventionTips":["Always pass fully qualified rule class names to --only, in quotes","Copy class names from your config or an IDE, not from prose/docs","Avoid registering identically-suffixed rule classes from multiple namespaces in one project"],"tags":["php","rector","cli","rule-selection","ambiguous-name"],"backgroundTag":"ambiguous-class-name-match","analyzedSha":"408fcb0ff1833e3d26cbc9b04c23a77565814a16","analyzedAt":"2026-08-21T05:11:02.643Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}