{"record":{"id":"b9bbde8ecab07cbd","repo":"flipped-aurora/gin-vue-admin","slug":"mcp-s-b9bbde","errorCode":null,"errorMessage":"MCP 健康检查失败: %s","messagePattern":"MCP 健康检查失败: (.+?)","errorType":"http","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/mcp/standalone_manager.go","lineNumber":266,"sourceCode":"\ttimeoutCtx, cancel := context.WithTimeout(ctx, mcpHealthCheckTimeout)\n\tdefer cancel()\n\n\treq, err := http.NewRequestWithContext(timeoutCtx, http.MethodGet, ResolveMCPHealthURL(), nil)\n\tif err != nil {\n\t\treturn false, err\n\t}\n\n\tresp, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\treturn false, err\n\t}\n\tdefer resp.Body.Close()\n\n\tif resp.StatusCode >= http.StatusOK && resp.StatusCode < http.StatusMultipleChoices {\n\t\treturn true, nil\n\t}\n\n\treturn false, fmt.Errorf(\"MCP 健康检查失败: %s\", resp.Status)\n}\n\nfunc waitForManagedProcess(ctx context.Context, meta *managedProcessMeta) (ManagedStandaloneStatus, error) {\n\tdeadline := time.NewTimer(mcpStartWaitTimeout)\n\tticker := time.NewTicker(300 * time.Millisecond)\n\tdefer deadline.Stop()\n\tdefer ticker.Stop()\n\n\tfor {\n\t\tselect {\n\t\tcase <-ctx.Done():\n\t\t\treturn GetManagedStandaloneStatus(context.Background()), ctx.Err()\n\t\tcase <-deadline.C:\n\t\t\treturn GetManagedStandaloneStatus(context.Background()), fmt.Errorf(\"等待 MCP 独立服务启动超时，请查看日志: %s\", meta.LogPath)\n\t\tcase <-ticker.C:\n\t\t\tcurrent := GetManagedStandaloneStatus(context.Background())\n\t\t\tif current.Reachable {\n\t\t\t\treturn current, nil","sourceCodeStart":248,"sourceCodeEnd":284,"githubUrl":"https://github.com/flipped-aurora/gin-vue-admin/blob/3136500ef380842b0eb6c4daa87c3f8a47fcf9e0/server/mcp/standalone_manager.go#L248-L284","documentation":"checkMCPHealth reports failure when the health-check HTTP request to the standalone MCP process succeeded at transport level but returned a non-2xx status code; the error carries the raw resp.Status (e.g. '503 Service Unavailable'). 2xx (200-299) is treated as healthy.","triggerScenarios":"GET to the MCP standalone health endpoint returns 401/404/429/5xx: process still initializing, auth token mismatch, wrong health route, or the process is overloaded/degraded.","commonSituations":"Polling during startup before the HTTP server is fully ready; health endpoint path changed between versions; reverse proxy in front returning 502/503; rate limiting returning 429.","solutions":["Wait briefly and retry — transient 503 during startup is common; the caller waitForManagedProcess already retries on a 300ms ticker.","Compare resp.Status in the error: 401/403 -> fix auth token; 404 -> health endpoint path changed; 5xx -> inspect the MCP log file.","Confirm the health URL/port in GVA_MCP_CONFIG matches the standalone server's actual listener.","If 5xx persists, check MCP logs for panics or failed dependency init."],"exampleFix":"// defensive polling wrapper\nfunc healthyEventually(url string, within time.Duration) error {\n    deadline := time.Now().Add(within)\n    for time.Now().Before(deadline) {\n        ok, err := checkMCPHealth(url)\n        if err == nil && ok { return nil }\n        time.Sleep(300 * time.Millisecond)\n    }\n    return fmt.Errorf(\"health check still failing after %s\", within)\n}","handlingStrategy":"retry","validationCode":"// pre-validate the health endpoint manually\nresp, err := http.Get(healthURL)\nif err != nil { return err }\nif resp.StatusCode < 200 || resp.StatusCode >= 300 {\n    return fmt.Errorf(\"health endpoint returned %s\", resp.Status)\n}","typeGuard":null,"tryCatchPattern":"ok, err := checkMCPHealth(url)\nif err != nil && strings.Contains(err.Error(), \"503\") {\n    time.Sleep(500 * time.Millisecond) // still initializing; retry\n    ok, err = checkMCPHealth(url)\n}","preventionTips":["Allow a warm-up window before requiring healthy status after start.","Keep the health route path stable across versions; document it.","Check the MCP log file whenever the status code is 5xx.","Pin auth tokens used by the health checker and rotate on a schedule."],"tags":["http","health-check","mcp","http-status"],"backgroundTag":"health-check-failed","analyzedSha":"3136500ef380842b0eb6c4daa87c3f8a47fcf9e0","analyzedAt":"2026-08-31T13:50:02.721Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}