{"record":{"id":"fef6d487b46c56cb","repo":"oraios/serena","slug":"found-multiple-len-symbol-candidates-symbols-ma","errorCode":null,"errorMessage":"Found multiple {len(symbol_candidates)} symbols matching '{name_path_pattern}'. They are: \n{json.dumps([s.to_dict(kind=True, relative_path=include_rel_path) for s in symbol_candidates], indent=2)}","messagePattern":"Found multiple (.+?) symbols matching '(.+?)'\\. They are: \n(.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/serena/symbol.py","lineNumber":794,"sourceCode":"            name_path_pattern,\n            include_kinds=include_kinds,\n            exclude_kinds=exclude_kinds,\n            substring_matching=substring_matching,\n            within_relative_path=within_relative_path,\n        )\n        if len(symbol_candidates) == 1:\n            return symbol_candidates[0]\n        elif len(symbol_candidates) == 0:\n            raise ValueError(f\"No symbol matching '{name_path_pattern}' found\")\n        else:\n            # There are multiple candidates.\n            # If only one of the candidates has the given pattern as its exact name path, return that one\n            exact_matches = [s for s in symbol_candidates if s.get_name_path() == name_path_pattern]\n            if len(exact_matches) == 1:\n                return exact_matches[0]\n            # otherwise, raise an error\n            include_rel_path = within_relative_path is not None\n            raise ValueError(\n                f\"Found multiple {len(symbol_candidates)} symbols matching '{name_path_pattern}'. \"\n                \"They are: \\n\" + json.dumps([s.to_dict(kind=True, relative_path=include_rel_path) for s in symbol_candidates], indent=2)\n            )\n\n    def find_by_location(self, location: LanguageServerSymbolLocation) -> LanguageServerSymbol | None:\n        if location.relative_path is None:\n            return None\n        lang_server = self.get_language_server(location.relative_path)\n        document_symbols = lang_server.request_document_symbols(location.relative_path)\n        for symbol_dict in document_symbols.iter_symbols():\n            symbol = LanguageServerSymbol(symbol_dict)\n            if symbol.location == location:\n                return symbol\n        return None\n\n    def find_referencing_symbols(\n        self,\n        name_path: str,","sourceCodeStart":776,"sourceCodeEnd":812,"githubUrl":"https://github.com/oraios/serena/blob/7fcbca7e62555ec2287ddb2f083caee805848ea6/src/serena/symbol.py#L776-L812","documentation":"When find_unique finds more than one candidate and exactly one exact name-path match cannot disambiguate them, it raises with the full candidate list (kind + relative path) serialized as JSON so the caller can pick the right name_path.","triggerScenarios":"Querying a short name like \"handle\" or \"__init__\" that exists in many classes/files; methods with the same name in base and derived classes; same-named symbols in different modules without qualifying the name path.","commonSituations":"Tools passing bare function names instead of dotted paths; large codebases with common helper names (run, main, to_dict); duplicate names across test and source trees.","solutions":["Pass the fully qualified name_path (e.g. \"MyClass.my_method\") so the exact-match disambiguation succeeds","Narrow the search with within_relative_path to the file/directory containing the target","Read the candidate list in the error message and retry with the exact name_path of the intended symbol"],"exampleFix":"// before\nmgr.find_unique(\"to_dict\")  # multiple hits\n// after\nmgr.find_unique(\"User.to_dict\")","handlingStrategy":"validation","validationCode":"matches = mgr.find_name_patterns(name_path)\nif len(matches) > 1:\n    raise AmbiguousSymbol(name_path, [m.get_name_path() for m in matches])","typeGuard":null,"tryCatchPattern":"try:\n    sym = mgr.find_unique(short_name)\nexcept ValueError as e:\n    if \"Found multiple\" in str(e):\n        candidates = parse_candidates(e)\n        sym = mgr.find_unique(disambiguate(candidates))\n    else:\n        raise","preventionTips":["Always pass class-qualified paths (Class.method) for common names","Narrow with within_relative_path to the owning file/module","Prefer unique symbol names to reduce collision risk"],"tags":["serena","symbols","ambiguity"],"backgroundTag":"ambiguous-symbol-match","analyzedSha":"7fcbca7e62555ec2287ddb2f083caee805848ea6","analyzedAt":"2026-08-29T00:04:09.619Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}