oraios/serena · error · ValueError

No symbol with name {name_path} found in file {relative_file

Error message

No symbol with name {name_path} found in file {relative_file_path}

What it means

_find_unique_symbol queries the JetBrains plugin client for symbols matching name_path within relative_file_path. If the result contains no symbols, ValueError is raised because the rename/lookup target simply does not exist in that file.

Source

Thrown at src/serena/code_editor.py:458

        def insert_text_at_position(self, pos: PositionInFile, text: str) -> None:
            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.

View on GitHub (pinned to 7fcbca7e62)

Solutions

Verify the file path is correct and the symbol is actually defined there
Use find_symbol without the file restriction to locate where the symbol lives
Check exact spelling and casing of name_path segments (e.g. 'Class.method')
Ensure the JetBrains plugin is running and the project is indexed

Example fix

// before
editor.rename_symbol("foo", "src/wrong.py", "bar")  # not in wrong.py
// after
editor.rename_symbol("foo", "src/correct.py", "bar")

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path
file = project_root / rel_path
assert file.is_file(), f"Missing file: {rel_path}"
# locate the symbol repo-wide first
result = client.find_symbol(name_path, include_body=False)
assert result["symbols"], f"Symbol {name_path} not found anywhere"

Try / catch

try:
    editor.rename_symbol(name_path, rel_path, new_name)
except ValueError as e:
    if str(e).startswith("No symbol with name"):
        loc = find_symbol_repo_wide(name_path)
        editor.rename_symbol(name_path, loc.relative_path, new_name)
    else:
        raise

Prevention

Validate relative_path exists before renaming
Run repo-wide find_symbol first to confirm where the symbol lives
Match name_path spelling/casing exactly

When it happens

Trigger: Calling rename_symbol (or anything calling _find_unique_symbol) with a name_path that does not exist in the given relative file — wrong file path, wrong symbol name, or symbol outside that file.

Common situations: Typos in name_path or relative_path; file moved/renamed since the path was captured; symbol defined in a different file than assumed; case-sensitivity mismatch in name_path segments.

Related errors

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