oraios/serena · error · ValueError

The explicitly passed file {within_relative_path} is ignored

Error message

The explicitly passed file {within_relative_path} is ignored, not returning overview.

What it means

ValueError raised by the overview API when the explicitly passed file path exists but is matched by the server's ignore rules; the library declines to return an overview for ignored files even on explicit requests. The message distinguishes it from the directory-symbols variant ([362]) by naming the file explicitly.

Source

Thrown at src/solidlsp/ls.py:2278

        :return: the top-level symbols in the given file.
        """
        return self.request_document_symbols(relative_file_path).root_symbols

    def request_overview(self, within_relative_path: str) -> dict[str, list[UnifiedSymbolInformation]]:
        """
        An overview of all symbols in the given file or directory.
        Raises a ValueError if a path to an ignored file is passed.

        :param within_relative_path: the relative path to the file or directory to get the overview of.
        :return: A mapping of all relative paths analyzed to lists of top-level symbols in the corresponding file.
        """
        abs_path = (Path(self.repository_root_path) / within_relative_path).resolve()
        if not abs_path.exists():
            raise FileNotFoundError(f"File or directory not found: {abs_path}")

        if abs_path.is_file():
            if self.is_ignored_path(within_relative_path):
                raise ValueError(f"The explicitly passed file {within_relative_path} is ignored, not returning overview.")
            symbols_overview = self.request_document_overview(within_relative_path)
            return {within_relative_path: symbols_overview}
        else:
            return self.request_dir_overview(within_relative_path)

    def request_hover(
        self, relative_file_path: str, line: int, column: int, file_buffer: LSPFileBuffer | None = None
    ) -> ls_types.Hover | None:
        """
        Raise a [textDocument/hover](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_hover) request to the Language Server
        to find the hover information at the given line and column in the given file. Wait for the response and return the result.

        :param relative_file_path: The relative path of the file that has the hover information
        :param line: The line number of the symbol
        :param column: The column number of the symbol
        :param file_buffer: The file buffer to use for the request. If not provided, the file will be read from disk.
            Can be used for optimizing number of file reads in downstream code
        """

View on GitHub (pinned to 7fcbca7e62)

Solutions

1. Choose a non-ignored source file, or un-ignore it (edit .gitignore / ignore patterns configured on the server).
2. Pre-check with ls.is_ignored_path(rel_path) and skip or warn in your tooling.
3. If analyzing generated code is required, pass ignore configuration that whitelists that path when creating the server.
4. Regenerate the file into a tracked location if it is a build artifact you need to inspect.

Example fix

// before
ls.request_overview("build/generated/schema.py")  # ignored
// after
if ls.is_ignored_path("build/generated/schema.py"):
    print("path is ignored; not requesting overview")
else:
    ls.request_overview("build/generated/schema.py")

abs_p = (Path(ls.repository_root_path) / rel_path).resolve()
if abs_p.exists() and ls.is_ignored_path(rel_path):
    raise ValueError(f"{rel_path} is ignored by server ignore rules")

def is_unignored_file(ls, rel: str) -> bool:
    p = (Path(ls.repository_root_path) / rel).resolve()
    return p.is_file() and not ls.is_ignored_path(rel)

try:
    overview = ls.request_overview(rel_path)
except ValueError as e:
    logging.info("skipping ignored file: %s", e)
    overview = {}

When it happens

Trigger: Calling request_overview (file branch: abs_path.is_file()) with a relative path that is_ignored_path() matches — e.g. files under .venv, build outputs, minified/generated files covered by gitignore.

Common situations: Requesting an overview for a lockfile, generated protobuf code, vendored dependency, or a file ignored via custom ignore configuration passed to the server constructor.

Related errors

• Explicitly requested symbols in '{within_relative_path}' whi
• File or directory not found: {within_abs_path}
• File or directory not found: {abs_path}
• Mode file not found: {path.resolve()}
• Error: Path does not exist: {project_root}

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