{"record":{"id":"a92e2e102a61f98d","repo":"oraios/serena","slug":"health-check-failed-failure-reason","errorCode":null,"errorMessage":"❌ Health check failed: {failure_reason}","messagePattern":"❌ Health check failed: (.+?)","errorType":"console","errorClass":"SystemExit","httpStatus":null,"severity":"error","filePath":"src/serena/cli.py","lineNumber":1047,"sourceCode":"                log.info(\"Health check completed successfully\")\n\n            # expected failures and unexpected exceptions are reported alike: both mean the project's\n            # tooling is not functional, which is the single thing this command is asked to determine\n            except Exception as e:\n                log.exception(\"Health check failed with exception: %s\", str(e))\n                failure_reason = str(e)\n\n            finally:\n                click.echo(f\"Log saved to: {log_file}\")\n\n        # the verdict is reported outside the checked region, so that a failure to write the report\n        # cannot be mistaken for a failure of the check itself; the exit code lets callers\n        # (CI, scripts) act on the verdict\n        if failure_reason is None:\n            click.echo(\"✅ Health check passed - All tools working correctly\")\n        else:\n            click.echo(f\"❌ Health check failed: {failure_reason}\")\n            raise SystemExit(1)\n\n\nclass ToolCommands(AutoRegisteringGroup):\n    \"\"\"Group for 'tool' subcommands.\"\"\"\n\n    def __init__(self) -> None:\n        super().__init__(\n            name=\"tools\",\n            help=\"Commands related to Serena's tools. You can run `serena tools <command> --help` for more info on each command.\",\n        )\n\n    @staticmethod\n    @click.command(\n        \"list\",\n        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`\",\n        context_settings={\"max_content_width\": _MAX_CONTENT_WIDTH},\n    )\n    @click.option(\"--quiet\", \"-q\", is_flag=True)","sourceCodeStart":1029,"sourceCodeEnd":1065,"githubUrl":"https://github.com/oraios/serena/blob/7fcbca7e62555ec2287ddb2f083caee805848ea6/src/serena/cli.py#L1029-L1065","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the failure_reason after the ❌ line and fix the underlying issue (missing files, broken LS, bad config).","Ensure the required language server is installed in the environment (especially CI).","Index the project (`serena project index`) before health-checking.","In scripts, handle exit code 1 explicitly rather than only parsing output."],"exampleFix":"// before (CI script ignores verdict)\nserena project health-check\ndeploy.sh\n// after\nserena project health-check || { echo 'serena health check failed'; exit 1; }\ndeploy.sh","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"proc = subprocess.run(['serena', 'project', 'health-check'], capture_output=True, text=True)\nif proc.returncode != 0:\n    reason = next((ln for ln in proc.stdout.splitlines() if 'Health check failed:' in ln), 'unknown')\n    print(f'Block pipeline: {reason}')\n    sys.exit(1)","preventionTips":["Treat exit code 1 as the verdict signal in CI, not just output parsing.","Install required language servers in CI images before running health checks.","Run the health check after project setup and indexing, not on fresh empty checkouts."],"tags":["cli","health-check","exit-code","ci"],"backgroundTag":"health-check-failed-exit-code","analyzedSha":"7fcbca7e62555ec2287ddb2f083caee805848ea6","analyzedAt":"2026-08-29T00:04:09.619Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}