oraios/serena · error · SystemExit

❌ Health check failed: {failure_reason}

Error message

❌ Health check failed: {failure_reason}

What it means

The `serena project health-check` CLI command reports its verdict on stdout. On failure it echoes `❌ Health check failed: <reason>` and raises SystemExit(1) so CI and scripts can act on the non-zero exit code. The message itself is the wrapper around any of the _HealthCheckFailure reasons above.

Source

Thrown at src/serena/cli.py:1047

                log.info("Health check completed successfully")

            # expected failures and unexpected exceptions are reported alike: both mean the project's
            # tooling is not functional, which is the single thing this command is asked to determine
            except Exception as e:
                log.exception("Health check failed with exception: %s", str(e))
                failure_reason = str(e)

            finally:
                click.echo(f"Log saved to: {log_file}")

        # the verdict is reported outside the checked region, so that a failure to write the report
        # cannot be mistaken for a failure of the check itself; the exit code lets callers
        # (CI, scripts) act on the verdict
        if failure_reason is None:
            click.echo("✅ Health check passed - All tools working correctly")
        else:
            click.echo(f"❌ Health check failed: {failure_reason}")
            raise SystemExit(1)


class ToolCommands(AutoRegisteringGroup):
    """Group for 'tool' subcommands."""

    def __init__(self) -> None:
        super().__init__(
            name="tools",
            help="Commands related to Serena's tools. You can run `serena tools <command> --help` for more info on each command.",
        )

    @staticmethod
    @click.command(
        "list",
        help="Prints an overview of the tools that are active by default (not just the active ones for your project). For viewing all tools, pass `--all / -a`",
        context_settings={"max_content_width": _MAX_CONTENT_WIDTH},
    )
    @click.option("--quiet", "-q", is_flag=True)

View on GitHub (pinned to 7fcbca7e62)

Solutions

1. Read the failure_reason after the ❌ line and fix the underlying issue (missing files, broken LS, bad config).
2. Ensure the required language server is installed in the environment (especially CI).
3. Index the project (`serena project index`) before health-checking.
4. In scripts, handle exit code 1 explicitly rather than only parsing output.

Example fix

// before (CI script ignores verdict)
serena project health-check
deploy.sh
// after
serena project health-check || { echo 'serena health check failed'; exit 1; }
deploy.sh

proc = subprocess.run(['serena', 'project', 'health-check'], capture_output=True, text=True)
if proc.returncode != 0:
    reason = next((ln for ln in proc.stdout.splitlines() if 'Health check failed:' in ln), 'unknown')
    print(f'Block pipeline: {reason}')
    sys.exit(1)

When it happens

Trigger: Any failing sub-check in `serena project health-check` — no analyzable file, empty overview, FindSymbol returning nothing, or any unexpected exception during tool execution — surfaces here with the captured reason.

Common situations: CI pipelines gating on serena health checks with a broken/misconfigured project; missing language servers in the CI image; empty repos in fresh checkouts; scripts that don't handle the exit code.

Related errors

• No analyzable files found
• No symbols found in target file {target_file}
• FindSymbolTool returned no results
• Cannot apply setup for client '{client}' (not found or not f
• Failed to set up Serena for {client}.

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