chenhg5/cc-connect · error

wecom: invalid callback_aes_key: %w

Error message

wecom: invalid callback_aes_key: %w

What it means

The callback_aes_key option must be the EncodingAESKey string from WeCom, which is 43 Base64-ish characters and decodes to a 32-byte AES key. New() validates this by calling decodeAESKey; if decoding fails (wrong length, non-standard characters), construction fails with this wrapped error.

Source

Thrown at platform/wecom/wecom.go:139

		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 == "" {
		apiBaseURL = defaultAPIBaseURL
	} else {
		parsed, err := url.Parse(apiBaseURL)
		if err != nil || (parsed.Scheme != "https" && parsed.Scheme != "http") || parsed.Host == "" {
			return nil, fmt.Errorf("wecom: invalid api_base_url %q: must be a valid http(s) URL", apiBaseURL)

View on GitHub (pinned to 4000b2338a)

Solutions

1. Copy the EncodingAESKey verbatim (43 characters) from the WeCom admin console 'Receive Messages' settings and re-enter it
2. Strip surrounding quotes, spaces, or newlines from the value in your config
3. Ensure you are using the EncodingAESKey, not the callback Token or corp_secret
4. Check decodeAESKey's expected format in platform/wecom and validate your key locally before startup

Example fix

// before
"callback_aes_key": "shortkey" // wrong length -> invalid callback_aes_key
// after
"callback_aes_key": "yLI7dD1234567890abcdefghijklmnopqrstuvwxyzABC" // 43-char EncodingAESKey

key, _ := opts["callback_aes_key"].(string)
if len(key) != 43 {
	return fmt.Errorf("EncodingAESKey must be exactly 43 characters, got %d", len(key))
}

When it happens

Trigger: Passing a callback_aes_key whose decoded length is not 32 bytes (decodeAESKey failure), e.g. a truncated copy-paste, a plaintext secret that is not the EncodingAESKey, extra whitespace/quotes, or using the corp_secret or Token field by mistake.

Common situations: Copy-pasting the EncodingAESKey from the WeCom console with surrounding quotes or whitespace; confusing the random Token with the EncodingAESKey; hand-generating an arbitrary key that isn't exactly 43 chars in the expected alphabet; an old key from a deleted app.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• wecom-ws: bot_id and bot_secret are required for websocket m
• wecom-ws: invalid aeskey base64 length
• wecom: callback_token and callback_aes_key are required
• wecom: invalid api_base_url %q: must be a valid http(s) URL
• 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/bc15ee1e54fcfe70. Report an issue: GitHub.