What causes "empty gateway URL in response" in chenhg5/cc-connect?

Re-fetch the access token and confirm it is non-empty before calling the gateway endpoint

empty gateway URL in response

Error message

empty gateway URL in response

What it means

QQ bot gateway fetch guard: the gateway endpoint responded with valid JSON but an empty url field, leaving no WebSocket endpoint to connect to — a server-side misconfiguration or regional outage rather than a client error.

Source

Thrown at platform/qqbot/qqbot.go:705

	if err != nil {
		return "", err
	}
	req.Header.Set("Authorization", "QQBot "+token)

	resp, err := core.HTTPClient.Do(req)
	if err != nil {
		return "", fmt.Errorf("gateway request failed: %w", err)
	}
	defer resp.Body.Close()

	var result struct {
		URL string `json:"url"`
	}
	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
		return "", fmt.Errorf("gateway response decode: %w", err)
	}
	if result.URL == "" {
		return "", fmt.Errorf("empty gateway URL in response")
	}
	return result.URL, nil
}

type wsPayload struct {
	Op int             `json:"op"`
	D  json.RawMessage `json:"d,omitempty"`
	S  *int64          `json:"s,omitempty"`
	T  string          `json:"t,omitempty"`
}

func (p *Platform) waitForHello(conn *websocket.Conn) error {
	_ = conn.SetReadDeadline(time.Now().Add(15 * time.Second))
	defer func() { _ = conn.SetReadDeadline(time.Time{}) }()

	var msg wsPayload
	if err := conn.ReadJSON(&msg); err != nil {
		return fmt.Errorf("waiting for hello: %w", err)

View on GitHub (pinned to 4000b2338a)

Solutions

Re-fetch the access token and confirm it is non-empty before calling the gateway endpoint
Verify appid/secret in config.toml are correct for the QQ bot app
Log the full gateway response to inspect unexpected fields
Check QQ open-platform docs/changelog for gateway API changes

Example fix

// before
if result.URL == "" {
    return "", fmt.Errorf("empty gateway URL in response")
}
// after
if result.URL == "" {
    return "", fmt.Errorf("empty gateway URL in response (status=%d)", resp.StatusCode)
}

Defensive patterns

Strategy: validation

Validate before calling

if token == "" {
    return errors.New("access token missing before gateway fetch")
}

Try / catch

gwURL, err := p.getGatewayURL()
if err != nil {
    if strings.Contains(err.Error(), "empty gateway URL") {
        _ = p.refreshAccessToken()
        gwURL, err = p.getGatewayURL()
    }
    if err != nil { return err }
}

Prevention

Refresh the access token before each gateway fetch or on 401
Validate appid/secret at startup with a doctor command
Log the full gateway JSON when url is empty

When it happens

Trigger: QQ API returns 200 with JSON lacking a populated url field — typically due to an expired/invalid access token or an API behavior change.

Common situations: Access token expired between fetch and use; appid/secret misconfigured so token is nominal; QQ API version change altering the response shape.

Understand the failure class

Background: "empty response", "returned no data", "empty embeddings": what HTTP 200-with-empty-body errors mean across libraries — this error's family across 36 libraries.

Related errors

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