oraios/serena · error · FileNotFoundError

Mode {name} not found in {SerenaPaths().user_modes_dir} or i

Error message

Mode {name} not found in {SerenaPaths().user_modes_dir} or in {SERENAS_OWN_MODE_YAMLS_DIR}.Available modes:
{cls.list_registered_mode_names()}

What it means

SerenaMode.get_path resolves a mode name to a YAML file, first in the user modes directory, then in Serena's bundled mode YAMLs. If neither contains <name>.yml, FileNotFoundError is raised, listing all registered modes to help the user pick a valid one.

Source

Thrown at src/serena/config/context_mode.py:96

    def get_path(cls, name: str, instance: Self | None = None) -> str:
        """Get the path to the YAML file for a mode.

        :param name: The name of the mode
        :param instance: Optional mode instance. If provided and it has a stored path, that path is returned.
        :return: The path to the mode's YAML file
        """
        # If we have an instance with a stored path, use that
        if instance is not None and instance._yaml_path is not None:
            return str(instance._yaml_path)

        fname = f"{name}.yml"
        custom_mode_path = os.path.join(SerenaPaths().user_modes_dir, fname)
        if os.path.exists(custom_mode_path):
            return custom_mode_path

        own_yaml_path = os.path.join(SERENAS_OWN_MODE_YAMLS_DIR, fname)
        if not os.path.exists(own_yaml_path):
            raise FileNotFoundError(
                f"Mode {name} not found in {SerenaPaths().user_modes_dir} or in {SERENAS_OWN_MODE_YAMLS_DIR}."
                f"Available modes:\n{cls.list_registered_mode_names()}"
            )
        return own_yaml_path

    @classmethod
    def from_name(cls, name: str) -> Self:
        """Load a registered Serena mode."""
        mode_path = cls.get_path(name)
        return cls.from_yaml(mode_path)

    @classmethod
    def from_name_internal(cls, name: str) -> Self:
        """Loads an internal Serena mode"""
        yaml_path = os.path.join(INTERNAL_MODE_YAMLS_DIR, f"{name}.yml")
        if not os.path.exists(yaml_path):
            raise FileNotFoundError(f"Internal mode '{name}' not found in {INTERNAL_MODE_YAMLS_DIR}")
        return cls.from_yaml(yaml_path)

View on GitHub (pinned to 7fcbca7e62)

Solutions

Run cls.list_registered_mode_names() (or check the error's listed modes) and use an exact existing mode name
Create a custom mode YAML at SerenaPaths().user_modes_dir/<name>.yml
Fix the mode name typo in your CLI flags or serena_config
After upgrading Serena, check release notes for renamed/removed modes

Example fix

// before
serena --mode editting
// after
serena --mode editing  # or a listed mode name

Defensive patterns

Strategy: validation

Validate before calling

from serena.config.context_mode import SerenaMode
names = SerenaMode.list_registered_mode_names()
assert mode_name in names, f"Unknown mode {mode_name}; available: {names}"

Try / catch

try:
    mode = SerenaMode.from_name(mode_name)
except FileNotFoundError as e:
    logger.warning("%s; falling back to default mode", e)
    mode = SerenaMode.from_name("default")

Prevention

List registered modes before configuring
Keep custom mode YAMLs in ~/.serena/modes with matching filenames
After Serena upgrades, re-check mode names in flags/config
Avoid typos by copying names from the error's available list

When it happens

Trigger: Starting Serena (or from_name('...')) with --mode <name> / mode config referencing a mode that has no YAML in either ~/.serena/modes or serena's resources; typo in mode name; referencing a mode removed in a newer Serena version.

Common situations: CLI flag typos like --mode interprative instead of interactive; copying config from docs of a different Serena version; deleting or renaming custom mode YAMLs; wrong user config dir (HOME change) so user modes aren't found.

Related errors

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