oraios/serena · error · ValueError

Path {relative_path} is ignored

Error message

Path {relative_path} is ignored

What it means

Raised by Project.validate_relative_path (src/serena/project.py:345) when require_not_ignored is true and the path matches the project's ignore rules (gitignore-style patterns or Serena ignore settings). The operation on that file is refused.

Source

Thrown at src/serena/project.py:345

    def validate_relative_path(self, relative_path: str, require_not_ignored: bool = False) -> None:
        """
        Validates that the given relative path is within the project directory
        (and, optionally, not ignored according to the project's ignore settings),
        raising a ValueError if the validation fails.

        :param relative_path: the path to validate, relative to the project root
        :param require_not_ignored: if True, the path must not be ignored according to the project's ignore settings
        """
        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

View on GitHub (pinned to 7fcbca7e62)

Solutions

1. Choose a target file that is not ignored, or reference the non-ignored source file
2. Adjust the project's ignore configuration (.serena/ignore or .gitignore) to un-ignore the required path
3. Set require_not_ignored=False only if you consciously accept operating on ignored paths

Example fix

// before
project.validate_relative_path('build/out.py', require_not_ignored=True)  # build/ ignored
// after
project.validate_relative_path('src/out.py', require_not_ignored=True)

if project.is_ignored_path(rel):
    logging.warning('%s is ignored; pick another file or adjust ignore config', rel)

try:
    project.validate_relative_path(rel, require_not_ignored=True)
except ValueError:
    rel = pick_non_ignored_alternative(rel, project)

When it happens

Trigger: Calling apply/validate_relative_path on a path under .git, node_modules, build outputs, or any pattern listed in the project's ignored patterns.

Common situations: Editing generated code or files inside ignored caches; new .gitignore rules added after the user started working with a file; explicit ignore config in .serena covering paths the agent needs.

Related errors

• Cannot use both fixed_tools and excluded_tools/included_opti
• Unknown language backend '{backend_str}': valid values are {
• Invalid line_ending: {value!r}. Valid values are: {valid}
• Invalid language server: '{orig_language_str}'.\nValid value
• activation_command_timeout must be a number, got: {activatio

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