chenhg5/cc-connect · error

cloud_web: token is required

Error message

cloud_web: token is required

What it means

The cloud_web platform constructor (New) validates options before building the platform. It throws this error when the `token` option is absent, not a string, or consists only of whitespace, because the cloud-web transport cannot authenticate without a token.

Source

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

	_ core.CardSender                = (*Platform)(nil)
	_ core.CardNavigable             = (*Platform)(nil)
	_ core.CardRefresher             = (*Platform)(nil)
	_ core.TypingIndicator           = (*Platform)(nil)
	_ core.MessageUpdater            = (*Platform)(nil)
	_ core.PreviewStarter            = (*Platform)(nil)
	_ core.PreviewCleaner            = (*Platform)(nil)
	_ core.AsyncRecoverablePlatform  = (*Platform)(nil)
)

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)

View on GitHub (pinned to 4000b2338a)

Solutions

1. Set `token = "<your cloud-web token>"` in the cloud_web platform's options in config.toml.
2. Verify the key is exactly `token` inside the cloud_web platform block (not another platform).
3. Confirm the value is a non-empty quoted string, not a number or unexpanded variable.
4. If sourcing from an env var, check it is actually set in the daemon's environment (systemd/launchd may have a minimal env).

Example fix

// before
opts := map[string]any{"name": "my_web"}
p, err := cloudweb.New(opts) // error: cloud_web: token is required
// after
opts := map[string]any{"name": "my_web", "token": os.Getenv("CLOUD_WEB_TOKEN")}
p, err := cloudweb.New(opts)

func validCloudWebOpts(opts map[string]any) error {
	tok, ok := opts["token"].(string)
	if !ok || strings.TrimSpace(tok) == "" {
		return fmt.Errorf("cloud_web: token must be a non-empty string before New")
	}
	return nil
}

func hasToken(opts map[string]any) bool {
	tok, ok := opts["token"].(string)
	return ok && strings.TrimSpace(tok) != ""
}

p, err := cloudweb.New(opts)
if err != nil {
	if strings.Contains(err.Error(), "token is required") {
		slog.Error("cloud_web platform skipped: set the `token` option in config.toml")
		return
	}
	return err
}

When it happens

Trigger: Calling cloudweb.New (directly or via core.CreatePlatform("cloud_web", opts) from config) where opts has no "token" key, opts["token"] is a non-string (e.g. number), or it is empty/whitespace after strings.TrimSpace.

Common situations: Missing token in config.toml [[platform]] options; token defined under the wrong platform block; token passed as a number; empty string from an unexpanded env placeholder; copy-pasting a config example without filling in the token.

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

• project %q has no yuanbao platform
• platform index %d out of range: project %q has %d yuanbao pl
• 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 is required for long_poll transport

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