chenhg5/cc-connect · error

wecom: callback_token and callback_aes_key are required

Error message

wecom: callback_token and callback_aes_key are required

What it means

wecom.New() requires callback_token and callback_aes_key in the options map when running in HTTP callback mode. These credentials come from your WeCom (WeChat Work) admin console and are needed to authenticate and decrypt inbound callback messages. If either is missing or has the wrong type (e.g. set to a non-string), the platform refuses to construct and returns this error.

Source

Thrown at platform/wecom/wecom.go:134

}

func New(opts map[string]any) (core.Platform, error) {
	mode, _ := opts["mode"].(string)
	if mode == "websocket" {
		return newWebSocket(opts)
	}

	corpID, _ := opts["corp_id"].(string)
	corpSecret, _ := opts["corp_secret"].(string)
	agentID, _ := opts["agent_id"].(string)
	callbackToken, _ := opts["callback_token"].(string)
	callbackAESKey, _ := opts["callback_aes_key"].(string)

	if corpID == "" || corpSecret == "" || agentID == "" {
		return nil, fmt.Errorf("wecom: corp_id, corp_secret, and agent_id are required")
	}
	if callbackToken == "" || callbackAESKey == "" {
		return nil, fmt.Errorf("wecom: callback_token and callback_aes_key are required")
	}

	aesKey, err := decodeAESKey(callbackAESKey)
	if err != nil {
		return nil, fmt.Errorf("wecom: invalid callback_aes_key: %w", err)
	}

	port, _ := opts["port"].(string)
	if port == "" {
		port = "8081"
	}
	path, _ := opts["callback_path"].(string)
	if path == "" {
		path = "/wecom/callback"
	}
	apiBaseURL, _ := opts["api_base_url"].(string)
	apiBaseURL = strings.TrimRight(strings.TrimSpace(apiBaseURL), "/")
	if apiBaseURL == "" {

View on GitHub (pinned to 4000b2338a)

Solutions

1. Add callback_token and callback_aes_key (both non-empty strings) from the WeCom app's 'Receive Messages' configuration page to the platform options
2. Verify the keys in your config use underscores exactly: callback_token, callback_aes_key
3. Confirm the values are strings in the config file (quoted), not empty or null
4. If you do not need callback mode, set mode = "websocket" in the options instead
5. Run the TestNew tests with a minimal valid opts map to confirm which field is missing

Example fix

// before
opts := map[string]any{"corp_id": "cid", "corp_secret": "sec", "agent_id": "1"}
p, err := wecom.New(opts) // error: callback_token and callback_aes_key are required
// after
opts := map[string]any{
  "corp_id": "cid", "corp_secret": "sec", "agent_id": "1",
  "callback_token": "myToken", "callback_aes_key": base43EncodingOfAESKey,
}
p, err := wecom.New(opts)

func validateWecomOpts(opts map[string]any) error {
	for _, k := range []string{"corp_id", "corp_secret", "agent_id", "callback_token", "callback_aes_key"} {
		v, _ := opts[k].(string)
		if v == "" {
			return fmt.Errorf("wecom: missing option %q", k)
		}
	}
	if len(opts["callback_aes_key"].(string)) != 43 {
		return fmt.Errorf("wecom: callback_aes_key should be 43 chars")
	}
	return nil
}

When it happens

Trigger: Calling New(opts) with opts lacking "callback_token" or "callback_aes_key", or with those keys set to nil/other types so the string type assertion yields "". Also triggered if they are present but empty strings. Not triggered in websocket mode (mode=="websocket" bypasses this check).

Common situations: Freshly wired config.toml where the [platform.wecom] section only has corp_id/corp_secret/agent_id; migrating from websocket mode to callback mode without adding the callback secrets; YAML/TOML keys misnamed (callback-token vs callback_token) so the lookup misses; values defined as environment-variable placeholders that resolve to empty.

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

• wecom-ws: bot_id and bot_secret are required for websocket m
• wecom: invalid callback_aes_key: %w
• wecom: invalid api_base_url %q: must be a valid http(s) URL
• PreflightRunAsUser: RunAsUser is empty
• tmux: 'session' option is required (name of the tmux session

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