oraios/serena · error · ValueError

No symbol matching '{name_path_pattern}' found

Error message

No symbol matching '{name_path_pattern}' found

What it means

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.

Source

Thrown at src/serena/symbol.py:785

    def find_unique(
        self,
        name_path_pattern: str,
        include_kinds: Sequence[SymbolKind] | None = None,
        exclude_kinds: Sequence[SymbolKind] | None = None,
        substring_matching: bool = False,
        within_relative_path: str | None = None,
    ) -> LanguageServerSymbol:
        symbol_candidates = self.find(
            name_path_pattern,
            include_kinds=include_kinds,
            exclude_kinds=exclude_kinds,
            substring_matching=substring_matching,
            within_relative_path=within_relative_path,
        )
        if len(symbol_candidates) == 1:
            return symbol_candidates[0]
        elif len(symbol_candidates) == 0:
            raise ValueError(f"No symbol matching '{name_path_pattern}' found")
        else:
            # There are multiple candidates.
            # If only one of the candidates has the given pattern as its exact name path, return that one
            exact_matches = [s for s in symbol_candidates if s.get_name_path() == name_path_pattern]
            if len(exact_matches) == 1:
                return exact_matches[0]
            # otherwise, raise an error
            include_rel_path = within_relative_path is not None
            raise ValueError(
                f"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)
            )

    def find_by_location(self, location: LanguageServerSymbolLocation) -> LanguageServerSymbol | None:
        if location.relative_path is None:
            return None
        lang_server = self.get_language_server(location.relative_path)
        document_symbols = lang_server.request_document_symbols(location.relative_path)

View on GitHub (pinned to 7fcbca7e62)

Solutions

  1. Verify the symbol exists with a broader find_symbol call (drop within_relative_path, enable substring_matching)
  2. Check spelling and the dotted name_path (e.g. MyClass.my_method) against the actual code
  3. Re-index/restart the language server if the symbol was just created

Example fix

// before
mgr.find_unique("parseConfig", within_relative_path="src/old")  # 0 hits
// after
candidates = mgr.find_name_patterns("parseConfig", substring_matching=True)
mgr.find_unique(candidates[0])
Defensive patterns

Strategy: try-catch

Validate before calling

candidates = mgr.find_name_patterns(name_path, substring_matching=True)
assert candidates, f"no symbol matching {name_path} exists"

Try / catch

try:
    sym = mgr.find_unique(name_path, within_relative_path=path)
except ValueError as e:
    if "No symbol matching" in str(e):
        sym = broaden_search_and_pick(name_path)
    else:
        raise

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of oraios/serena@7fcbca7e62 (2026-08-29). Data as JSON: /api/errors/19d9ed774c3a34be. Report an issue: GitHub.