oraios/serena · error · FileNotFoundError

Relative path {start_path} not found.

Error message

Relative path {start_path} not found.

What it means

Raised by Project.gather_source_files (src/serena/project.py:355) when the start path (project_root joined with the given relative_path) does not exist on disk. Gather enumerates source files under this path, so it must be an existing file or directory.

Source

Thrown at src/serena/project.py:355

        if FileProxy.is_external_path(relative_path):
            return

        if not self.is_path_in_project(relative_path):
            raise ValueError(f"{relative_path=} points outside the project root ({self.project_root})")

        if require_not_ignored:
            if self.is_ignored_path(relative_path):
                raise ValueError(f"Path {relative_path} is ignored")

    def gather_source_files(self, relative_path: str = "") -> list[str]:
        """Retrieves relative paths of all source files, optionally limited to the given path

        :param relative_path: if provided, restrict search to this path
        """
        rel_file_paths = []
        start_path = os.path.join(self.project_root, relative_path)
        if not os.path.exists(start_path):
            raise FileNotFoundError(f"Relative path {start_path} not found.")
        if os.path.isfile(start_path):
            return [relative_path]
        else:
            for root, dirs, files in os.walk(start_path, followlinks=True):
                # prevent recursion into ignored directories
                dirs[:] = [d for d in dirs if not self.is_ignored_path(os.path.join(root, d))]

                # collect non-ignored files
                for file in files:
                    abs_file_path = os.path.join(root, file)
                    try:
                        if not self.is_ignored_path(abs_file_path, ignore_non_source_files=True):
                            try:
                                rel_file_path = os.path.relpath(abs_file_path, start=self.project_root)
                            except Exception:
                                log.warning(
                                    "Ignoring path '%s' because it appears to be outside of the project root (%s)",
                                    abs_file_path,

View on GitHub (pinned to 7fcbca7e62)

Solutions

1. Verify the path exists: os.path.exists(os.path.join(project.project_root, relative_path)) before calling
2. Call with the default '' (whole project root) or an existing subdirectory
3. Refresh the caller's cached path list before re-indexing

Example fix

// before
files = project.gather_source_files('src/old_module')  # deleted
// after
start = os.path.join(project.project_root, 'src/old_module')
files = project.gather_source_files('src/old_module') if os.path.exists(start) else project.gather_source_files()

start = os.path.join(project.project_root, relative_path)
if not os.path.exists(start):
    raise FileNotFoundError(f'Cannot gather: {start} missing')

try:
    files = project.gather_source_files(relative_path)
except FileNotFoundError:
    files = project.gather_source_files()  # fall back to whole project

When it happens

Trigger: Calling gather_source_files with a relative path to a deleted/moved file or directory, or an empty directory reference removed after a rebuild; also triggered indirectly by indexing/health-check callers when project files vanished.

Common situations: Stale cached paths after a refactor; case-mismatched directory names on case-sensitive filesystems; git checkout switching removed a folder just before indexing.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• Error: Path does not exist: {project_root}
• Error: Path is not a directory: {project_root}
• Project root not found: {project_root}
• File or directory {relative_path} does not exist in the proj
• Mode file not found: {path.resolve()}

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