{"record":{"id":"19d9ed774c3a34be","repo":"oraios/serena","slug":"no-symbol-matching-name-path-pattern-found","errorCode":null,"errorMessage":"No symbol matching '{name_path_pattern}' found","messagePattern":"No symbol matching '(.+?)' found","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/serena/symbol.py","lineNumber":785,"sourceCode":"    def find_unique(\n        self,\n        name_path_pattern: str,\n        include_kinds: Sequence[SymbolKind] | None = None,\n        exclude_kinds: Sequence[SymbolKind] | None = None,\n        substring_matching: bool = False,\n        within_relative_path: str | None = None,\n    ) -> LanguageServerSymbol:\n        symbol_candidates = self.find(\n            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)","sourceCodeStart":767,"sourceCodeEnd":803,"githubUrl":"https://github.com/oraios/serena/blob/7fcbca7e62555ec2287ddb2f083caee805848ea6/src/serena/symbol.py#L767-L803","documentation":"SymbolManager.find_unique requires exactly one symbol to match a name-path pattern. When zero candidates are returned it raises this ValueError, because all downstream operations (references, edits, diagnostics) need a unique target symbol.","triggerScenarios":"find_symbol with a misspelled or stale name_path; symbol lives in a different relative path than the within_relative_path filter; symbol was renamed/deleted; regex/substring matching flags exclude the target.","commonSituations":"Refactors renamed a function but tooling still uses the old path; searching only within a subdirectory that doesn't contain the symbol; case-sensitivity mismatches in name paths.","solutions":["Verify the symbol exists with a broader find_symbol call (drop within_relative_path, enable substring_matching)","Check spelling and the dotted name_path (e.g. MyClass.my_method) against the actual code","Re-index/restart the language server if the symbol was just created"],"exampleFix":"// before\nmgr.find_unique(\"parseConfig\", within_relative_path=\"src/old\")  # 0 hits\n// after\ncandidates = mgr.find_name_patterns(\"parseConfig\", substring_matching=True)\nmgr.find_unique(candidates[0])","handlingStrategy":"try-catch","validationCode":"candidates = mgr.find_name_patterns(name_path, substring_matching=True)\nassert candidates, f\"no symbol matching {name_path} exists\"","typeGuard":null,"tryCatchPattern":"try:\n    sym = mgr.find_unique(name_path, within_relative_path=path)\nexcept ValueError as e:\n    if \"No symbol matching\" in str(e):\n        sym = broaden_search_and_pick(name_path)\n    else:\n        raise","preventionTips":["Use fully qualified dotted name paths","Drop or widen within_relative_path when unsure of the file","Re-run after renames; keep name paths in sync with refactors"],"tags":["serena","symbols","not-found"],"backgroundTag":"symbol-not-found","analyzedSha":"7fcbca7e62555ec2287ddb2f083caee805848ea6","analyzedAt":"2026-08-29T00:04:09.619Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}