oraios/serena · error · FileNotFoundError

Context {name} not found in {SerenaPaths().user_contexts_dir

Error message

Context {name} not found in {SerenaPaths().user_contexts_dir} or in {SERENAS_OWN_CONTEXT_YAMLS_DIR}.Available contexts:
{cls.list_registered_context_names()}

What it means

Analogous to modes: SerenaContext.get_path resolves a context name to a YAML in the user contexts dir, then Serena's bundled context YAMLs. If <name>.yml exists in neither, FileNotFoundError is raised listing all registered context names.

Source

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

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

        :param name: The name of the context
        :param instance: Optional context instance. If provided and it has a stored path, that path is returned.
        :return: The path to the context'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_context_path = os.path.join(SerenaPaths().user_contexts_dir, fname)
        if os.path.exists(custom_context_path):
            return custom_context_path

        own_yaml_path = os.path.join(SERENAS_OWN_CONTEXT_YAMLS_DIR, fname)
        if not os.path.exists(own_yaml_path):
            raise FileNotFoundError(
                f"Context {name} not found in {SerenaPaths().user_contexts_dir} or in {SERENAS_OWN_CONTEXT_YAMLS_DIR}."
                f"Available contexts:\n{cls.list_registered_context_names()}"
            )
        return own_yaml_path

    @classmethod
    def from_name(cls, name: str) -> Self:
        """Load a registered Serena context."""
        legacy_name_mapping = {
            "ide-assistant": "claude-code",
        }
        if name in legacy_name_mapping:
            log.warning(
                f"Context name '{name}' is deprecated and has been renamed to '{legacy_name_mapping[name]}'. "
                f"Please update your configuration; refer to the configuration guide for more details: "
                "https://oraios.github.io/serena/02-usage/050_configuration.html#contexts"
            )
            name = legacy_name_mapping[name]

View on GitHub (pinned to 7fcbca7e62)

Solutions

  1. Use an exact context name from the error's 'Available contexts' list (cls.list_registered_context_names())
  2. Create the custom context YAML at SerenaPaths().user_contexts_dir/<name>.yml
  3. Fix the context name in CLI flags or serena_config
  4. If upgrading, rename to the new context names per release notes

Example fix

// before
serena --context codex
// after
serena --context codex-cli  # name from the available contexts list
Defensive patterns

Strategy: validation

Validate before calling

from serena.config.context_mode import SerenaContext
names = SerenaContext.list_registered_context_names()
assert context_name in names, f"Unknown context {context_name}; available: {names}"

Try / catch

try:
    ctx = SerenaContext.from_name(context_name)
except FileNotFoundError as e:
    logger.warning("%s; falling back to default context", e)
    ctx = SerenaContext.from_name("default")

Prevention

When it happens

Trigger: Starting Serena with --context <name> or context config referencing a context that has no YAML in ~/.serena/contexts or Serena's own context resources — typo in context name, context removed/renamed in a newer version, or custom context file never created.

Common situations: Typos like --context deskop-app instead of desktop-app; following outdated tutorials referencing removed contexts (e.g. old 'ide-assistant' names); custom context YAMLs in a different HOME/config dir; containers where ~/.serena wasn't mounted.

Related errors

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