chenhg5/cc-connect · error

qq: invalid API response

Error message

qq: invalid API response

What it means

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.

Source

Thrown at platform/qq/qq.go:572

		return nil, err
	}

	p.mu.Lock()
	err = p.conn.WriteMessage(websocket.TextMessage, data)
	p.mu.Unlock()
	if err != nil {
		return nil, fmt.Errorf("qq: ws write: %w", err)
	}

	select {
	case raw := <-ch:
		var resp struct {
			Status  string          `json:"status"`
			RetCode int             `json:"retcode"`
			Data    json.RawMessage `json:"data"`
		}
		if json.Unmarshal(raw, &resp) != nil {
			return nil, fmt.Errorf("qq: invalid API response")
		}
		if resp.RetCode != 0 {
			return nil, fmt.Errorf("qq: API %s failed (retcode=%d)", action, resp.RetCode)
		}
		var result map[string]any
		_ = json.Unmarshal(resp.Data, &result)
		return result, nil

	case <-time.After(15 * time.Second):
		return nil, fmt.Errorf("qq: API %s timeout", action)
	}
}

// callHTTPAPI calls a OneBot v11 HTTP endpoint (e.g. /upload_group_file).
// Used for file operations — avoids WebSocket message size limits and
// file-path issues across Windows/WSL/Docker boundaries.
// Requires http_url to be configured.
func (p *Platform) callHTTPAPI(action string, params map[string]any) (map[string]any, error) {

View on GitHub (pinned to 4000b2338a)

Solutions

1. Upgrade or check the OneBot implementation (NapCat, Lagrange, go-cqhttp) for v11 API response conformance.
2. Verify echo correlation: the response frame must carry the same echo ID as the request — mismatched correlation pulls in wrong frames.
3. Log the raw frame that failed to parse to identify what was actually received.
4. If a proxy sits between the adapter and OneBot, confirm it passes WebSocket text frames unmodified.
5. Retry the API call — a transient mixed frame will usually be followed by a well-formed response.

var probe struct {
    Status  string          `json:"status"`
    RetCode int             `json:"retcode"`
    Data    json.RawMessage `json:"data"`
}
if err := json.Unmarshal(rawFrame, &probe); err != nil {
    slog.Warn("non-conformant onebot frame", "raw", string(rawFrame))
}

if _, err := p.callAPI("get_login_info", nil); err != nil {
    if strings.Contains(err.Error(), "invalid API response") {
        slog.Error("onebot implementation returns non-v11 responses; check implementation/version")
    }
    return err
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "failed to unmarshal" / json.Unmarshal errors: why parsing a response into a Go struct fails and how to fix it — this error's family across 23 libraries.

Related errors

• decode upload init response: %w
• parse releases: %w
• cloud_web: parse register_ack: %w
• %s: create card entity: parse response: %w
• qq: ws connect failed (%s): %w

AI-assisted analysis of chenhg5/cc-connect@4000b2338a (2026-09-06). Data as JSON: /api/errors/d1599eca8da8ddb9. Report an issue: GitHub.