{"record":{"id":"d1599eca8da8ddb9","repo":"chenhg5/cc-connect","slug":"qq-invalid-api-response","errorCode":null,"errorMessage":"qq: invalid API response","messagePattern":"qq: invalid API response","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"platform/qq/qq.go","lineNumber":572,"sourceCode":"\t\treturn nil, err\n\t}\n\n\tp.mu.Lock()\n\terr = p.conn.WriteMessage(websocket.TextMessage, data)\n\tp.mu.Unlock()\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"qq: ws write: %w\", err)\n\t}\n\n\tselect {\n\tcase raw := <-ch:\n\t\tvar resp struct {\n\t\t\tStatus  string          `json:\"status\"`\n\t\t\tRetCode int             `json:\"retcode\"`\n\t\t\tData    json.RawMessage `json:\"data\"`\n\t\t}\n\t\tif json.Unmarshal(raw, &resp) != nil {\n\t\t\treturn nil, fmt.Errorf(\"qq: invalid API response\")\n\t\t}\n\t\tif resp.RetCode != 0 {\n\t\t\treturn nil, fmt.Errorf(\"qq: API %s failed (retcode=%d)\", action, resp.RetCode)\n\t\t}\n\t\tvar result map[string]any\n\t\t_ = json.Unmarshal(resp.Data, &result)\n\t\treturn result, nil\n\n\tcase <-time.After(15 * time.Second):\n\t\treturn nil, fmt.Errorf(\"qq: API %s timeout\", action)\n\t}\n}\n\n// callHTTPAPI calls a OneBot v11 HTTP endpoint (e.g. /upload_group_file).\n// Used for file operations — avoids WebSocket message size limits and\n// file-path issues across Windows/WSL/Docker boundaries.\n// Requires http_url to be configured.\nfunc (p *Platform) callHTTPAPI(action string, params map[string]any) (map[string]any, error) {","sourceCodeStart":554,"sourceCodeEnd":590,"githubUrl":"https://github.com/chenhg5/cc-connect/blob/4000b2338aa6e850c99df54f8b0ed6ed7460b401/platform/qq/qq.go#L554-L590","documentation":"Returned by callAPI when the response frame received on the echo channel cannot be unmarshaled into the expected OneBot envelope {status, retcode, data}. The OneBot side (or an intermediary) sent something that is not a valid OneBot v11 API response — often an event frame or non-JSON payload landed on the reply channel instead of the actual response.","triggerScenarios":"The pending-response channel receives a raw message (matched by echo) that is malformed or not the expected envelope shape; json.Unmarshal(raw, &resp) returns an error.","commonSituations":"Non-standard OneBot implementation returning non-conformant responses; an intermediary proxy mangling frames; echo-correlation bug where an unrelated event message is captured as the reply; OneBot firmware/plugin emitting text instead of JSON for errors.","solutions":["Upgrade or check the OneBot implementation (NapCat, Lagrange, go-cqhttp) for v11 API response conformance.","Verify echo correlation: the response frame must carry the same echo ID as the request — mismatched correlation pulls in wrong frames.","Log the raw frame that failed to parse to identify what was actually received.","If a proxy sits between the adapter and OneBot, confirm it passes WebSocket text frames unmodified.","Retry the API call — a transient mixed frame will usually be followed by a well-formed response."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"var probe struct {\n    Status  string          `json:\"status\"`\n    RetCode int             `json:\"retcode\"`\n    Data    json.RawMessage `json:\"data\"`\n}\nif err := json.Unmarshal(rawFrame, &probe); err != nil {\n    slog.Warn(\"non-conformant onebot frame\", \"raw\", string(rawFrame))\n}","typeGuard":null,"tryCatchPattern":"if _, err := p.callAPI(\"get_login_info\", nil); err != nil {\n    if strings.Contains(err.Error(), \"invalid API response\") {\n        slog.Error(\"onebot implementation returns non-v11 responses; check implementation/version\")\n    }\n    return err\n}","preventionTips":["Use OneBot v11-conformant implementations (NapCat, Lagrange, go-cqhttp) kept up to date","Log raw failing frames for post-mortem","Ensure echo IDs are unique per request and matched exactly on response","Avoid intermediaries that transform WebSocket payloads"],"tags":["json","websocket","onebot","response-parsing"],"backgroundTag":"json-unmarshal-failed","analyzedSha":"4000b2338aa6e850c99df54f8b0ed6ed7460b401","analyzedAt":"2026-09-06T11:45:09.575Z","contentChangedAt":"2026-09-06T11:45:09.575Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}