What causes "gateway_url must be a valid wss URL" in Tencent/WeKnora?

Set gateway_url to a complete URL like wss://api.sgroup.qq.com/websocket

gateway_url must be a valid wss URL

Error message

gateway_url must be a valid wss URL

What it means

Validation helper validateGatewayURL rejects a configured QQ bot gateway_url that fails URL parsing or has no host. Empty values are allowed (the default gateway is used), so this only fires on a non-empty but malformed override.

Source

Thrown at internal/im/qqbot/client.go:98

	if err != nil || u.Host == "" {
		return fmt.Errorf("invalid qqbot api_base_url: must be a valid http(s) URL")
	}
	if u.Scheme != "http" && u.Scheme != "https" {
		return fmt.Errorf("invalid qqbot api_base_url: must use http or https")
	}
	if err := secutils.ValidateURLForSSRF(raw); err != nil {
		return fmt.Errorf("invalid qqbot api_base_url: %w (for private deployments, add the hostname to SSRF_WHITELIST)", err)
	}
	return nil
}

func validateGatewayURL(raw string) error {
	if strings.TrimSpace(raw) == "" {
		return nil
	}
	u, err := url.Parse(raw)
	if err != nil || u.Host == "" {
		return fmt.Errorf("gateway_url must be a valid wss URL")
	}
	if u.Scheme != "wss" {
		return fmt.Errorf("gateway_url must use wss")
	}
	checkURL := *u
	checkURL.Scheme = "https"
	if err := secutils.ValidateURLForSSRF(checkURL.String()); err != nil {
		return fmt.Errorf(
			"gateway_url failed SSRF validation: %w (for private deployments, add the hostname to SSRF_WHITELIST)",
			err,
		)
	}
	return nil
}

func (c *Client) SendC2CMessage(ctx context.Context, openID, content, msgID string) error {
	path := fmt.Sprintf("/v2/users/%s/messages", openID)
	return c.sendText(ctx, path, content, msgID)

View on GitHub (pinned to 988cbb0330)

Solutions

Set gateway_url to a complete URL like wss://api.sgroup.qq.com/websocket
Ensure the host portion is present and the value has no stray whitespace or scheme typos
Leave gateway_url empty to let the client discover the gateway from the API

Example fix

// before
GATEWAY_URL=wss://   // empty host
// after
GATEWAY_URL=wss://api.sgroup.qq.com/websocket

Defensive patterns

Strategy: validation

Validate before calling

func validGateway(u string) bool {
    p, err := url.Parse(strings.TrimSpace(u))
    return err == nil && p.Host != "" && p.Scheme == "wss"
}

Try / catch

client, err := NewClient(cfg)
if err != nil && strings.Contains(err.Error(), "gateway_url must be a valid wss URL") {
    return fmt.Errorf("fix GATEWAY_URL config: %w", err)
}

Prevention

Validate gateway_url with url.Parse at config load
Leave gateway_url empty to use API discovery
Avoid hand-concatenated URL strings

When it happens

Trigger: gateway_url is set to a string that url.Parse rejects or that yields an empty Host (e.g. "wss://", "://bad", a bare path, or whitespace-mangled value).

Common situations: Typo in the gateway URL; missing host after copying from docs; env var interpolated as empty/partial value; trailing characters breaking the URL.

Related errors

AI-assisted analysis of Tencent/WeKnora@988cbb0330 (2026-09-02). Data as JSON: /api/errors/d0b4b4dcf28ff58d. Report an issue: GitHub.