oraios/serena · error · ValueError

Unknown language backend '{backend_str}': valid values are {

Error message

Unknown language backend '{backend_str}': valid values are {[b.value for b in LanguageBackend]}

What it means

SerenaConfig parses the language_server.language_backend setting into the LanguageBackend enum via from_str(). This ValueError is raised when the configured string does not case-insensitively match any enum member's value (e.g. only 'lsp' or 'jetbrains' are valid).

Source

Thrown at src/serena/config/serena_config.py:215

class LanguageBackend(Enum):
    LSP = "LSP"
    """
    Use the language server protocol (LSP), spawning freely available language servers
    via the SolidLSP library that is part of Serena
    """
    JETBRAINS = "JetBrains"
    """
    Use the Serena plugin in your JetBrains IDE.
    (requires the plugin to be installed and the project being worked on to be open in your IDE)
    """

    @staticmethod
    def from_str(backend_str: str) -> "LanguageBackend":
        for backend in LanguageBackend:
            if backend.value.lower() == backend_str.lower():
                return backend
        raise ValueError(f"Unknown language backend '{backend_str}': valid values are {[b.value for b in LanguageBackend]}")

    def is_lsp(self) -> bool:
        return self == LanguageBackend.LSP

    def is_jetbrains(self) -> bool:
        return self == LanguageBackend.JETBRAINS

    def get_lsp_tool_class_replacements(self) -> "dict[type[Tool], type[Tool]]":
        """
        :return: mapping from LSP tool classes to replacement tool classes (functional replacements)
        """
        match self:
            case LanguageBackend.LSP:
                return {}
            case LanguageBackend.JETBRAINS:
                from ..tools import jetbrains_tools, symbol_tools

                return {

View on GitHub (pinned to 7fcbca7e62)

Solutions

Set language_backend to exactly 'lsp' or 'jetbrains' (case-insensitive) in the config file.
Check for typos, trailing whitespace, or quoting issues in the YAML value.
If migrating from an older Serena version, update deprecated backend names to the current enum values.
Inspect the enum in src/serena/config/serena_config.py to see the authoritative list of valid values.

Example fix

# before (serena_config.yml)
language_server:
  language_backend: language-server
# after
language_server:
  language_backend: lsp

Defensive patterns

Strategy: validation

Validate before calling

from serena.config.serena_config import LanguageBackend

VALID_BACKENDS = [b.value for b in LanguageBackend]

def validate_backend(backend_str: str) -> None:
    if backend_str.strip().lower() not in [v.lower() for v in VALID_BACKENDS]:
        raise ValueError(f"language_backend must be one of {VALID_BACKENDS}, got {backend_str!r}")

Type guard

def is_valid_backend(backend_str: str) -> bool:
    return backend_str.lower() in [b.value.lower() for b in LanguageBackend]

Try / catch

try:
    backend = LanguageBackend.from_str(cfg["language_backend"])
except ValueError as e:
    log.warning("%s; falling back to LSP", e)
    backend = LanguageBackend.LSP

Prevention

Only use 'lsp' or 'jetbrains' for language_backend in YAML.
Derive valid values from the enum rather than hardcoding strings.
Add schema validation (e.g. yamale/jsonschema) for serena_config.yml.
Strip whitespace from config values before parsing.

When it happens

Trigger: Setting language_backend: <invalid> in serena_config.yml (or wherever from_config_file/_from_dict parse it), passing an arbitrary string to LanguageBackend.from_str() directly, or using an outdated value from a renamed enum member.

Common situations: Typo like 'LSP ' with trailing whitespace, 'language-server', 'pyright', or copying config from an older Serena version where other backend values existed; editing YAML by hand without IDE validation.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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