{"record":{"id":"416f78fe22e1edaa","repo":"linshenkx/prompt-optimizer","slug":"health-check-failed","errorCode":null,"errorMessage":"Health check failed","messagePattern":"Health check failed","errorType":"http","errorClass":null,"httpStatus":503,"severity":"error","filePath":"packages/mcp-server/src/health.ts","lineNumber":29,"sourceCode":"\nexport function buildHealthzResponse(healthStatus: MCPHealthStatus): {\n  statusCode: number;\n  body: MCPHealthStatus;\n} {\n  return {\n    statusCode: isHealthyStatus(healthStatus) ? 200 : 503,\n    body: healthStatus\n  };\n}\n\nexport function registerHealthzRoute(app: Express, healthProvider: HealthStatusProvider): void {\n  app.get('/healthz', async (_req, res) => {\n    try {\n      const healthStatus = await healthProvider.getHealthStatus();\n      const { statusCode, body } = buildHealthzResponse(healthStatus);\n      res.status(statusCode).json(body);\n    } catch (error) {\n      res.status(503).json({\n        initialized: false,\n        services: {},\n        error: error instanceof Error ? error.message : 'Health check failed'\n      });\n    }\n  });\n}\n","sourceCodeStart":11,"sourceCodeEnd":37,"githubUrl":"https://github.com/linshenkx/prompt-optimizer/blob/3e677b1d9f7e0493c142c175560531e7ae786dce/packages/mcp-server/src/health.ts#L11-L37","documentation":"The /healthz route of the MCP server calls healthProvider.getHealthStatus(); if that promise rejects (or a non-Error is thrown), the catch block returns HTTP 503 with initialized:false and the error message, defaulting to the literal 'Health check failed' when the thrown value is not an Error instance.","triggerScenarios":"GET /healthz while a dependency checked by getHealthStatus is down or throws — e.g. storage/DB unreachable, a service not yet initialized — or when getHealthStatus itself has a bug and throws a string/non-Error value (which surfaces as the generic message).","commonSituations":"Kubernetes/container probes hitting /healthz before dependencies are ready; misconfigured connection strings causing getHealthStatus to reject; version changes to the health provider API throwing TypeError instead of structured status.","solutions":["Check the response body's error field and the server logs to see which underlying dependency failed (the generic message means a non-Error was thrown — log the raw value).","Fix the underlying dependency (DB/storage connection, env config) so getHealthStatus resolves.","Configure liveness/readiness probe thresholds to tolerate startup, or have getHealthStatus return degraded status objects instead of throwing."],"exampleFix":"// before\nres.status(503).json({ initialized: false, services: {}, error: error instanceof Error ? error.message : 'Health check failed' });\n// after (also log the raw failure for diagnosis)\nconsole.error('[healthz] non-Error failure:', error);\nres.status(503).json({ initialized: false, services: {}, error: error instanceof Error ? error.message : String(error) });","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"const isHealthzFailure = (body: unknown): body is { initialized: false; error: string } =>\n  typeof body === 'object' && body !== null && (body as any).initialized === false","tryCatchPattern":"const res = await fetch(`${MCP_URL}/healthz`)\nif (res.status === 503) {\n  const body = await res.json().catch(() => null)\n  log.warn('MCP unhealthy:', body?.error ?? 'unknown')\n  // retry with backoff; if the message is the generic 'Health check failed', a non-Error was thrown server-side\n}","preventionTips":["Probe /healthz with retry/backoff at startup instead of assuming readiness.","Ensure getHealthStatus returns status objects rather than throwing; wrap its internals in try/catch that returns degraded status.","Configure orchestrator probes (k8s readiness) with appropriate initialDelaySeconds/failureThreshold."],"tags":["health-check","http","mcp-server","startup","kubernetes"],"backgroundTag":"health-check-endpoint-unhealthy","analyzedSha":"3e677b1d9f7e0493c142c175560531e7ae786dce","analyzedAt":"2026-08-27T21:29:16.709Z","schemaVersion":2},"datasetVersion":"2026-08-28T00:17:15.603Z"}