chenhg5/cc-connect · error

internal: unknown mode %q

Error message

internal: unknown mode %q

What it means

resolveWeixinSetupMode maps the user's requested setup mode (--new/--qr or bind) to an internal constant for `cc-connect weixin setup`. If the internal requested value isn't one of the recognized modes, it returns "internal: unknown mode %q". This is a defensive programmer-error guard rather than a user-facing input validation failure — invalid flags should be rejected earlier.

Source

Thrown at cmd/cc-connect/weixin.go:230

func resolveWeixinSetupMode(requested, token string) (string, error) {
	switch requested {
	case weixinSetupModeAuto:
		if token != "" {
			return weixinSetupModeBind, nil
		}
		return weixinSetupModeNew, nil
	case weixinSetupModeBind:
		if token == "" {
			return "", errors.New("bind mode requires --token")
		}
		return weixinSetupModeBind, nil
	case weixinSetupModeNew:
		if token != "" {
			return "", errors.New("new/QR mode does not accept --token; use `cc-connect weixin bind --token ...`")
		}
		return weixinSetupModeNew, nil
	default:
		return "", fmt.Errorf("internal: unknown mode %q", requested)
	}
}

type weixinQRLoginOptions struct {
	APIBaseURL string
	RouteTag   string
	BotType    string
	Timeout    time.Duration
	QRImage    string
	Debug      bool
}

type weixinQRLoginResult struct {
	BotToken    string
	IlinkBotID  string
	BaseURL     string
	IlinkUserID string
}

View on GitHub (pinned to 4000b2338a)

Solutions

1. Inspect the %q value in the message and trace which code path produced it; it should only ever be one of the defined weixinSetupMode* constants.
2. Add a case (or validation) for the new mode in resolveWeixinSetupMode's switch.
3. Check flag parsing for `weixin setup` — user input should be validated to a fixed set before reaching this resolver.
4. Update any external scripts calling setup with a mode string to use supported modes only.

Example fix

// before
mode := flagGetString(cmd, "mode") // arbitrary input flows in
m, err := resolveWeixinSetupMode(mode)

// after
if mode != "" && mode != weixinSetupModeNew && mode != weixinSetupModeBind {
    return fmt.Errorf("invalid --mode %q", mode)
}
m, err := resolveWeixinSetupMode(mode)

validModes := map[string]bool{"new": true, "bind": true}
if !validModes[requested] {
    return fmt.Errorf("invalid setup mode %q; want new|bind", requested)
}

mode, err := resolveWeixinSetupMode(requested)
if err != nil {
    return fmt.Errorf("weixin setup: %w", err) // surfaces internal invariant break
}

When it happens

Trigger: runWeixinSetup calls resolveWeixinSetupMode with a mode string that was not set by flag parsing — i.e. a code path constructing the mode value incorrectly, or a new mode constant added in one place but not in the switch.

Common situations: A developer adds a new weixin setup subcommand/mode but forgets to add a case to resolveWeixinSetupMode; refactoring renames a mode constant; a plugin or script passes an arbitrary string directly into the setup flow.

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

• bind mode requires --token
• new/QR mode does not accept --token; use `cc-connect weixin
• unknown validation error
• empty qrcode_img_content from server
• 二维码多次过期，请重试 setup

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