oraios/serena · error · SystemExit

Cannot apply setup for client '{client}' (not found or not f

Error message

Cannot apply setup for client '{client}' (not found or not functional).

What it means

The `serena setup <client>` CLI command looks up a client setup handler by name and runs handler.is_applicable() to verify the client's config directory actually exists on this machine. If not applicable it prints this message and raises SystemExit(1), because applying the setup (writing MCP config) would target a nonexistent client installation.

Source

Thrown at src/serena/cli.py:223

    @staticmethod
    @click.command(
        "setup",
        help="Set up Serena for use with a specific client by registering it as an MCP server.",
        context_settings={"max_content_width": _MAX_CONTENT_WIDTH},
    )
    @click.argument(
        "client",
        type=click.Choice([h.name for h in client_setup_handlers]),
    )
    def setup(client: str) -> None:
        # find the matching handler
        handler = next(h for h in client_setup_handlers if h.name == client)

        # check applicability
        if not handler.is_applicable():
            click.echo(f"\nCannot apply setup for client '{client}' (not found or not functional).\n")
            raise SystemExit(1)

        # apply the setup
        if handler.apply():
            click.echo(f"\nSerena has been successfully set up for {client}.\n")
        else:
            click.echo(f"\nFailed to set up Serena for {client}.\n")
            raise SystemExit(1)

    @staticmethod
    @click.command("start-mcp-server", help="Starts the Serena MCP server.", context_settings={"max_content_width": _MAX_CONTENT_WIDTH})
    @click.option("--project", "project", type=PROJECT_TYPE, default=None, help="Path or name of project to activate at startup.")
    @click.option("--project-file", "project", type=PROJECT_TYPE, default=None, help="[DEPRECATED] Use --project instead.")
    @click.argument("project_file_arg", type=PROJECT_TYPE, required=False, default=None, metavar="")
    @click.option(
        "--context", type=str, default=DEFAULT_CONTEXT, show_default=True, help="Built-in context name or path to custom context YAML."
    )
    @click.option(
        "--mode",

View on GitHub (pinned to 7fcbca7e62)

Solutions

Install/launch the target client at least once so its config directory exists, then rerun `serena setup <client>`.
Configure the client manually: add the Serena MCP server entry to the client's MCP config file yourself.
Verify you're running inside the same environment (same HOME/OS) where the client is installed; note WSL vs Windows paths.
Pick a different, supported client via the interactive setup prompt.

Example fix

// before
serena setup cursor   # ~/.cursor missing
// after
mkdir -p ~/.cursor && open cursor once, or edit mcp config manually:
// { "mcpServers": { "serena": { "command": "serena", "args": ["start-mcp-server"] } } }

Defensive patterns

Strategy: validation

Validate before calling

import os, pathlib
def client_config_exists(handler) -> bool:
    return callable(getattr(handler, 'is_applicable', None)) and handler.is_applicable()

Try / catch

try:
    handler = next(h for h in client_setup_handlers if h.name == client)
except StopIteration:
    raise SystemExit(f"Unsupported client: {client}")
if not handler.is_applicable():
    raise SystemExit(f"Client '{client}' not detected; install it or configure MCP manually")

Prevention

Install and launch the client at least once before running serena setup.
Run serena setup in the same OS/environment (HOME, WSL vs native) where the client is installed.
Fall back to manually editing the client's MCP config when automated setup can't detect the client.

When it happens

Trigger: Running `serena setup <client-name>` where the client's configuration directory cannot be found on the system (e.g. no ~/.claude, ~/.cursor, etc. for the chosen handler), or with a client name whose handler reports not functional.

Common situations: Client not installed on the machine; client installed under a non-default path (custom HOME, portable installs); typos or unsupported client name selected in the interactive picker; running in a container/WSL where the client lives on the host.

Related errors

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