oraios/serena · error · ValueError

Found multiple {len(symbols)} symbols with name {name_path}

Error message

Found multiple {len(symbols)} symbols with name {name_path} in file {relative_file_path}: {json.dumps(symbols, indent=2)}

What it means

When the JetBrains find_symbol query returns more than one symbol with the same name_path in the same file, _find_unique_symbol raises ValueError and includes all matches as JSON, because renaming requires an unambiguous target.

Source

Thrown at src/serena/code_editor.py:460

            self._content, _, _ = TextUtils.insert_text_at_position(self._content, pos.line, pos.col, text)

    @contextmanager
    def _open_file_context(self, relative_path: str) -> Iterator["CodeEditor.EditedFile"]:
        yield self.EditedFile(relative_path, self._project)

    def _save_edited_file(self, edited_file: "CodeEditor.EditedFile") -> None:
        super()._save_edited_file(edited_file)
        with JetBrainsPluginClient.from_project(self._project) as client:
            client.refresh_file(edited_file.relative_path)

    def _find_unique_symbol(self, name_path: str, relative_file_path: str) -> JetBrainsSymbol:
        with JetBrainsPluginClient.from_project(self._project) as client:
            result = client.find_symbol(name_path, relative_path=relative_file_path, include_body=False, depth=0, include_location=True)
            symbols = result["symbols"]
            if not symbols:
                raise ValueError(f"No symbol with name {name_path} found in file {relative_file_path}")
            if len(symbols) > 1:
                raise ValueError(
                    f"Found multiple {len(symbols)} symbols with name {name_path} in file {relative_file_path}: "
                    + json.dumps(symbols, indent=2)
                )
            return JetBrainsSymbol(symbols[0], self._project)

    def rename_symbol(
        self,
        name_path: str | None,
        relative_path: str,
        new_name: str,
        rename_in_comments: bool = False,
        rename_in_text_occurrences: bool = False,
    ) -> str:
        """
        Renames a code symbol, file, or directory throughout the codebase.

        :param name_path: the name path of the symbol to rename. Set to None for renaming a file or directory.
        :param relative_path: if `name_path` is passed, the relative path of the file containing the symbol.

View on GitHub (pinned to 7fcbca7e62)

Solutions

1. Extend name_path to a fully qualified path that uniquely identifies the symbol (e.g. 'Class.outer.inner')
2. Inspect the JSON list in the error message and pick the intended symbol's precise name_path
3. Rename at a unique definition location instead of by name lookup
4. Check for duplicate definitions accidentally introduced by copy-paste and remove one

Example fix

// before: ambiguous 'process' -> 3 matches
editor.rename_symbol("process", "src/app.py", "process_data")
// after: disambiguated
editor.rename_symbol("DataProcessor.process", "src/app.py", "process_data")

result = client.find_symbol(name_path, relative_path=rel_path, include_location=True)
if len(result["symbols"]) != 1:
    raise ValueError("name_path is ambiguous; qualify it further")

try:
    editor.rename_symbol(name_path, rel_path, new_name)
except ValueError as e:
    if "Found multiple" in str(e):
        matches = json.loads(str(e).split(": ", 2)[-1])
        name_path = choose_unique_name_path(matches)
        editor.rename_symbol(name_path, rel_path, new_name)
    else:
        raise

When it happens

Trigger: rename_symbol on a name_path that matches multiple symbols in one file — e.g. overloaded methods, same-named nested symbols, or name_path segments that don't disambiguate scopes.

Common situations: Method overloads with identical names; shadowed names in nested scopes; languages where the same name can denote multiple entities in one file (getter/setter pairs, extensions).

Related errors

• No symbol with name {name_path} found in file {relative_file
• Symbol '{name_path}' does not have a valid position in file
• Language server for {lang_server.language_id} returned no re
• Renaming symbol '{name_path}' to '{new_name}' resulted in no
• Found no Serena service in a JetBrains IDE instance for the

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