chenhg5/cc-connect · critical

qqbot: failed to connect gateway: %w

Error message

qqbot: failed to connect gateway: %w

What it means

Start() obtains an access token and then calls connectGateway(ctx) to fetch the WebSocket gateway URL and establish the bot's event connection. If connecting fails, Start cancels the context it just created (avoiding a leak) and returns this wrapped error. The gateway is the bot's only event channel, so a failed connection means the platform cannot start.

Source

Thrown at platform/qqbot/qqbot.go:205

// Start connects to the QQ Bot gateway and begins receiving events.
func (p *Platform) Start(handler core.MessageHandler) error {
	p.handler = handler
	if err := p.loadMessageCache(); err != nil {
		slog.Warn("qqbot: load message cache failed", "error", err)
	}

	// Get initial access token
	if err := p.refreshToken(); err != nil {
		return fmt.Errorf("qqbot: failed to get access token: %w", err)
	}

	ctx, cancel := context.WithCancel(context.Background())
	p.ctx = ctx
	p.cancel = cancel

	if err := p.connectGateway(ctx); err != nil {
		cancel()
		return fmt.Errorf("qqbot: failed to connect gateway: %w", err)
	}

	slog.Info("qqbot: connected to QQ Bot gateway", "sandbox", p.sandbox)
	return nil
}

// Reply sends a message as a reply to an incoming message.
func (p *Platform) Reply(ctx context.Context, replyCtx any, content string) error {
	return p.Send(ctx, replyCtx, content)
}

// Send sends a message to the conversation identified by replyCtx.
func (p *Platform) Send(ctx context.Context, replyCtx any, content string) error {
	rctx, ok := replyCtx.(*replyContext)
	if !ok {
		return fmt.Errorf("qqbot: invalid reply context")
	}

View on GitHub (pinned to 4000b2338a)

Solutions

1. Confirm outbound HTTPS + WSS connectivity to the QQ Bot gateway host from the running machine.
2. Fix the token problem first if the inner error mentions the token — re-check credentials and sandbox flag.
3. Verify the intents option values are valid for your bot's permissions (invalid intents can cause gateway rejection).
4. Retry Start() with exponential backoff; QQ rate-limits gateway connection attempts.
5. Read the wrapped inner error (%w) for the specific HTTP status or WebSocket handshake failure.

Example fix

// before
if err := platform.Start(ctx); err != nil { return err } // no diagnostics
// after
if err := platform.Start(ctx); err != nil {
    if strings.Contains(err.Error(), "failed to connect gateway") {
        slog.Error("qq gateway unreachable", "error", err, "hint", "check wss connectivity and intents")
    }
    return err
}

// Reachability probe for gateway host before Start
conn, err := net.DialTimeout("tcp", "api.sgroup.qq.com:443", 5*time.Second)
if err != nil { return fmt.Errorf("gateway host unreachable: %w", err) }
conn.Close()

if err := p.Start(ctx); err != nil {
    var netErr net.Error
    if errors.As(err, &netErr) { /* schedule reconnect with backoff */ }
    cancel()
}

When it happens

Trigger: Calling Start() when the gateway URL request fails (network error, 4xx/5xx), the returned gateway URL is unreachable, the WebSocket handshake is rejected, or the token obtained moments earlier has already been invalidated.

Common situations: Firewall blocking wss:// to api.sgroup.qq.com or sandbox gateway hosts; invalid token cached and reused; QQ gateway rejecting intents payload; sandbox/prod mismatch causing gateway auth rejection; DNS or IPv6 issues in containers.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• qq: ws connect failed (%s): %w
• qqbot: failed to get access token: %w
• ws connect: %w
• wecom-ws: ack timeout
• cloud_web: gateway listen: %w

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