chenhg5/cc-connect · error

qq: HTTP %s failed: %w

Error message

qq: HTTP %s failed: %w

What it means

This error is returned by callHTTPAPI when the Go HTTP client fails to execute the OneBot-style HTTP API request to the QQ server (client.Do returned an error). It wraps the underlying transport error, so the root cause (DNS failure, connection refused, timeout, TLS error) is in the wrapped chain. It means the request never got a valid HTTP response, not that the server rejected it.

Source

Thrown at platform/qq/qq.go:610

		return nil, fmt.Errorf("qq: http_url not configured")
	}
	body, err := json.Marshal(params)
	if err != nil {
		return nil, err
	}
	url := p.httpURL + "/" + action
	req, err := http.NewRequest("POST", url, bytes.NewReader(body))
	if err != nil {
		return nil, err
	}
	req.Header.Set("Content-Type", "application/json")
	if p.token != "" {
		req.Header.Set("Authorization", "Bearer "+p.token)
	}
	client := &http.Client{Timeout: 120 * time.Second}
	resp, err := client.Do(req)
	if err != nil {
		return nil, fmt.Errorf("qq: HTTP %s failed: %w", action, err)
	}
	defer resp.Body.Close()

	raw, err := io.ReadAll(resp.Body)
	if err != nil {
		return nil, fmt.Errorf("qq: HTTP %s read body: %w", action, err)
	}

	var apiResp struct {
		Status  string          `json:"status"`
		RetCode int             `json:"retcode"`
		Data    json.RawMessage `json:"data"`
		Message string          `json:"message"`
	}
	if json.Unmarshal(raw, &apiResp) != nil {
		return nil, fmt.Errorf("qq: HTTP %s invalid response", action)
	}
	if apiResp.RetCode != 0 {

View on GitHub (pinned to 4000b2338a)

Solutions

1. Verify the QQ OneBot HTTP endpoint host/port in config and that the server is running (curl the endpoint manually).
2. Inspect the wrapped %w error in logs to identify DNS vs connection vs timeout root cause.
3. If timeouts occur, check server responsiveness or raise/retry; the client timeout is fixed at 120s in callHTTPAPI.
4. Check firewall/proxy settings between cc-connect and the QQ HTTP server.

Example fix

// before
resp, err := client.Do(req)
if err != nil {
    return nil, fmt.Errorf("qq: HTTP %s failed: %w", action, err)
}
// after (retry once on transient transport failure)
resp, err := client.Do(req)
if err != nil {
    resp, err = client.Do(req)
}
if err != nil {
    return nil, fmt.Errorf("qq: HTTP %s failed: %w", action, err)
}

// Go: check endpoint reachability before calling the library
conn, err := net.DialTimeout("tcp", "127.0.0.1:5700", 3*time.Second)
if err != nil { return fmt.Errorf("qq endpoint unreachable: %w", err) }
conn.Close()

if err != nil {
    var netErr net.Error
    if errors.As(err, &netErr) && netErr.Timeout() {
        // retry with backoff
    }
    return fmt.Errorf("qq api transport error: %w", err)
}

When it happens

Trigger: Any callHTTPAPI invocation (e.g. via parseMessage) where http.Client.Do fails: server unreachable, wrong host/port in config, 120s timeout exceeded, TLS handshake failure, or no network.

Common situations: QQ bot HTTP server (OneBot/go-cqhttp) not running or listening on a different port; DNS misconfiguration; firewall blocking the endpoint; server hanging past the 120s client timeout; transient network outage.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

• qq: HTTP %s read body: %w
• openai tts: request: %w
• dingtalk: proactive send request: %w
• max: edit message: %w
• HTTP %d

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