What causes "unsupported dingtalk mode: %s" in Tencent/WeKnora?

Set mode to exactly "websocket" (recommended, stream mode) or "webhook".

unsupported dingtalk mode: %s

Error message

unsupported dingtalk mode: %s

What it means

The DingTalk factory supports two modes: "webhook" and "websocket" (the default via stream mode). Any other value for the mode credential/setting hits the default branch and returns this error naming the unsupported mode string.

Source

Thrown at internal/im/dingtalk/factory.go:48

		case "websocket":
			wsCtx, wsCancel := context.WithCancel(context.Background())
			go im.RunSupervised(wsCtx, im.SupervisorConfig{
				Name: fmt.Sprintf("DingTalk channel %s", channel.ID),
				Connect: func(ctx context.Context) (func(), error) {
					client := NewLongConnClient(clientID, clientSecret, msgHandler)
					if err := client.Start(ctx); err != nil {
						client.Close()
						return nil, err
					}
					return client.Close, nil
				},
			})

			adapter := NewAdapter(clientID, clientSecret, cardTemplateID)
			return adapter, wsCancel, nil

		default:
			return nil, nil, fmt.Errorf("unsupported dingtalk mode: %s", mode)
		}
	}
}

View on GitHub (pinned to 988cbb0330)

Solutions

Set mode to exactly "websocket" (recommended, stream mode) or "webhook".
Remove the mode field entirely if you want the default (websocket) behavior.
Check casing — values are matched case-sensitively, so "Webhook" will fail.

Example fix

// before
"mode": "stream"
// after
"mode": "websocket"

Defensive patterns

Strategy: validation

Validate before calling

allowed := map[string]bool{"webhook": true, "websocket": true, "": true}
if !allowed[mode] {
    return fmt.Errorf("dingtalk mode must be \"webhook\" or \"websocket\", got %q", mode)
}

Type guard

func validDingTalkMode(m string) bool { return m == "" || m == "webhook" || m == "websocket" }

Try / catch

adapter, cancel, err := factory(ctx, channel, handler)
if err != nil {
    if strings.HasPrefix(err.Error(), "unsupported dingtalk mode") {
        return fmt.Errorf("set mode to \"websocket\" (default) or \"webhook\"")
    }
    return err
}

Prevention

Only use documented mode values: webhook, websocket.
Omit the mode field to get the websocket default.
Watch for casing and whitespace when mode comes from env or config.

When it happens

Trigger: Configuring a DingTalk IM channel with mode set to something other than "webhook" or "websocket" (e.g. "stream", "ws", "Webhook" with wrong casing).

Common situations: Copy-pasting mode values from docs for other IM providers; typo or casing differences; older config using a mode name that was never supported.

Related errors

AI-assisted analysis of Tencent/WeKnora@988cbb0330 (2026-09-02). Data as JSON: /api/errors/044005eb81e55713. Report an issue: GitHub.