chenhg5/cc-connect · error

cloud_web: base_url is required for long_poll transport

Error message

cloud_web: base_url is required for long_poll transport

What it means

cloud-web's Platform constructor validates its transport configuration. When transport is set to "long_poll", the constructor requires a non-empty base_url because the polling transport needs an HTTP endpoint to poll for events and send messages. This error is thrown by New when baseURL is empty or whitespace-only for that transport.

Source

Thrown at platform/cloud-web/cloudweb.go:108

	sendPath, _ := opts["send_path"].(string)
	longPollMS := pickInt(opts["long_poll_timeout_ms"])

	allowFrom, _ := opts["allow_from"].(string)
	core.CheckAllowFrom(name, allowFrom)
	shareInChannel, _ := opts["share_session_in_channel"].(bool)
	groupReplyAll, _ := opts["group_reply_all"].(bool)

	var tp transport
	switch transportKind {
	case "websocket":
		resolved := resolveWSURL(baseURL, wsURL)
		if strings.TrimSpace(resolved) == "" {
			return nil, fmt.Errorf("cloud_web: ws_url or base_url is required for websocket transport")
		}
		tp = newWSTransport(resolved, token, name, project)
	case "long_poll":
		if strings.TrimSpace(baseURL) == "" {
			return nil, fmt.Errorf("cloud_web: base_url is required for long_poll transport")
		}
		tp = newPollTransport(baseURL, token, name, project, eventsPath, sendPath, longPollMS)
	case "gateway":
		if strings.TrimSpace(baseURL) == "" && strings.TrimSpace(registerURL) != "" {
			baseURL = deriveBaseURL(registerURL)
		}
		if strings.TrimSpace(baseURL) == "" && strings.TrimSpace(registerURL) == "" {
			return nil, fmt.Errorf("cloud_web: base_url or register_url is required for gateway transport")
		}
		if strings.TrimSpace(registerURL) != "" && strings.TrimSpace(publicURL) == "" {
			return nil, fmt.Errorf("cloud_web: public_url is required when register_url is set for gateway transport")
		}
		tp = newGatewayTransport(baseURL, token, name, project, listen, webhookPath, registerURL, publicURL, sendPath)
	}

	return &Platform{
		name:           name,
		project:        project,

View on GitHub (pinned to 4000b2338a)

Solutions

1. Set base_url in the cloud_web platform config to the reachable HTTP endpoint of the cloud-web service, e.g. base_url = "https://cloud.example.com"
2. If you intended websocket transport instead, set ws_url (or base_url) and transport = "websocket"
3. Verify the value is not empty after trimming (no "" or " ") before constructing the platform
4. Run the doctor / startup config validation to catch the missing field before runtime

Example fix

// before
[platform.cloud_web]
transport = "long_poll"
# base_url missing

// after
[platform.cloud_web]
transport = "long_poll"
base_url = "https://cloud.example.com"

if strings.TrimSpace(cfg.Transport) == "long_poll" && strings.TrimSpace(cfg.BaseURL) == "" {
    return fmt.Errorf("cloud_web: base_url must be set when transport is long_poll")
}

When it happens

Trigger: Calling New (via mustNew or the platform factory) with options resolving transport to "long_poll" while base_url is unset, empty string, or only whitespace.

Common situations: A config.toml [platform.cloud_web] section that sets transport = "long_poll" but omits base_url; an env-var-driven setup where the BASE_URL variable is not exported; copying a websocket example config and switching transport without adding base_url.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• cloud_web: transport must be websocket, long_poll, or gatewa
• cloud_web: ws_url or base_url is required for websocket tran
• cloud_web: base_url or register_url is required for gateway
• tmux: 'session' option is required (name of the tmux session
• config: relay.visibility must be "full", "summary", or "none

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