oraios/serena · error · ValueError

Expected a file path, but got a directory path: {relative_pa

Error message

Expected a file path, but got a directory path: {relative_path}. 

What it means

get_symbol_overview requires a file path; passing a directory path raises ValueError even though the low-level symbol retriever supports directories. The tool intentionally narrows the contract to files so callers get a predictable, file-scoped symbol listing.

Source

Thrown at src/serena/tools/symbol_tools.py:107

            shortened_results = [make_depth_0_result, make_kind_counts]

        return self._limit_length(result_json_str, max_answer_chars, shortened_result_factories=shortened_results)

    def get_symbol_overview(self, relative_path: str, depth: int = 0) -> list[LanguageServerSymbol.OutputDict]:
        """
        :param relative_path: relative path to a source file
        :param depth: the depth up to which descendants shall be retrieved
        :return: a list of symbol dictionaries representing the symbol overview of the file
        """
        symbol_retriever = self.create_language_server_symbol_retriever()

        # The symbol overview is capable of working with both files and directories,
        # but we want to ensure that the user provides a file path.
        file_path = os.path.join(self.project.project_root, relative_path)
        if not os.path.exists(file_path):
            raise FileNotFoundError(f"File or directory {relative_path} does not exist in the project.")
        if os.path.isdir(file_path):
            raise ValueError(f"Expected a file path, but got a directory path: {relative_path}. ")
        if not symbol_retriever.can_analyze_file(relative_path):
            raise ValueError(
                f"Cannot extract symbols from file {relative_path}. Active language servers: {[l.value for l in self.agent.get_active_language_server_ids()]}"
            )

        symbols = symbol_retriever.get_symbol_overview(relative_path)[relative_path]

        def child_inclusion_predicate(s: LanguageServerSymbol) -> bool:
            return not s.is_low_level()

        symbol_dicts = []
        for symbol in symbols:
            symbol_dicts.append(
                symbol.to_dict(
                    name_path=False,
                    name=True,
                    depth=depth,
                    kind=True,

View on GitHub (pinned to 7fcbca7e62)

Solutions

1. Pass an individual file path instead of a directory
2. Iterate over directory files yourself and call get_symbol_overview per file
3. Use a directory-capable listing (e.g. the JetBrains overview tool or find_file) to enumerate files first

Example fix

// before
get_symbol_overview.apply(relative_path='src')
// ValueError: Expected a file path...

// after
for f in Path('src').rglob('*.py'):
    overview = get_symbol_overview.apply(relative_path=str(f))

from pathlib import Path
p = Path(project_root) / relative_path
if p.is_dir():
    files = [str(f.relative_to(project_root)) for f in p.rglob('*') if f.is_file()]
    overviews = [symbol_tool.get_symbol_overview(relative_path=f) for f in files]
else:
    overview = symbol_tool.get_symbol_overview(relative_path=relative_path)

def is_file_path(rel: str, root: str) -> bool:
    p = Path(root) / rel
    return p.is_file()

try:
    overview = symbol_tool.get_symbol_overview(relative_path=rel)
except ValueError as e:
    if 'directory path' in str(e):
        overview = [symbol_tool.get_symbol_overview(relative_path=str(f))
                    for f in (Path(root) / rel).rglob('*') if f.is_file()]
    else:
        raise

When it happens

Trigger: Calling get_symbol_overview with relative_path pointing to a directory (e.g. 'src' or 'src/'), or a path that exists but is a directory rather than a file.

Common situations: User asks 'show me all symbols in the src folder'; agent passes the project root '.'; glob-like or trailing-slash paths that resolve to directories.

Related errors

• {relative_path=} points outside the project root ({self.proj
• name_path_pattern must not be empty or contain only wildcard
• File or directory {relative_path} does not exist in the proj
• Cannot insert after this symbol (not a function, class or me
• Cannot use both fixed_tools and excluded_tools/included_opti

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