cloud_web: transport must be websocket, long_poll, or gatewa

Error message

cloud_web: transport must be websocket, long_poll, or gateway

What it means

The cloud_web platform constructor validates the `transport` option against a fixed set of supported values. It throws this error when transport is set to something other than "websocket", "long_poll", or "gateway" — an unknown transport kind cannot be instantiated.

Source

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

func New(opts map[string]any) (core.Platform, error) {
	name, _ := opts["name"].(string)
	if name == "" {
		name = "cloud_web"
	}
	project, _ := opts["cc_project"].(string)
	token, _ := opts["token"].(string)
	if strings.TrimSpace(token) == "" {
		return nil, fmt.Errorf("cloud_web: token is required")
	}

	transportKind, _ := opts["transport"].(string)
	if transportKind == "" {
		transportKind = "websocket"
	}
	switch transportKind {
	case "websocket", "long_poll", "gateway":
	default:
		return nil, fmt.Errorf("cloud_web: transport must be websocket, long_poll, or gateway")
	}

	baseURL, _ := opts["base_url"].(string)
	wsURL, _ := opts["ws_url"].(string)
	listen, _ := opts["listen"].(string)
	webhookPath, _ := opts["webhook_path"].(string)
	registerURL, _ := opts["register_url"].(string)
	publicURL, _ := opts["public_url"].(string)
	eventsPath, _ := opts["events_path"].(string)
	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

View on GitHub (pinned to 4000b2338a)

Solutions

Set transport to one of exactly: "websocket", "long_poll", or "gateway".
Fix common typos: "longpoll" → "long_poll", "ws" → "websocket".
Omit the option entirely to use the default ("websocket").
Check the release notes/changelog if upgrading — the transport value may have been renamed.

Example fix

// before
opts := map[string]any{"token": tok, "transport": "longpoll"} // invalid
// after
opts := map[string]any{"token": tok, "transport": "long_poll"}

Defensive patterns

Strategy: validation

Validate before calling

var validTransports = map[string]bool{"websocket": true, "long_poll": true, "gateway": true}
func transportOK(opts map[string]any) bool {
	t, _ := opts["transport"].(string)
	return t == "" || validTransports[t]
}

Type guard

func isSupportedTransport(v any) bool {
	s, ok := v.(string)
	if !ok { return false }
	switch s {
	case "websocket", "long_poll", "gateway":
		return true
	}
	return false
}

Try / catch

p, err := cloudweb.New(opts)
if err != nil {
	if strings.Contains(err.Error(), "transport must be") {
		slog.Error("invalid transport; use websocket, long_poll, or gateway", "got", opts["transport"])
		return
	}
	return err
}

Prevention

Copy transport values exactly from config.example.toml.
Remember snake_case: long_poll, not longpoll.
Omit transport to accept the websocket default.
Run a config validation pass at startup to catch typos early.

When it happens

Trigger: Calling cloudweb.New with opts["transport"] set to any string outside {websocket, long_poll, gateway}, e.g. "ws", "polling", "longpoll", "sse", or a typo.

Common situations: Typo in config.toml (`transport = "longpoll"` instead of "long_poll"); copying transport names from another platform's config; older config using a removed transport value after a version upgrade.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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