chenhg5/cc-connect · error

%s: create card entity: %w

Error message

%s: create card entity: %w

What it means

Wraps a transport/client error from withFreshTenantAccessTokenRetry around the POST /open-apis/cardkit/v1/cards (Create Card Entity) call. This is the %w wrap of whatever the lark SDK returned — network failure, auth failure, or retry exhaustion — and means the card entity was never created so streaming updates cannot proceed.

Source

Thrown at platform/feishu/feishu.go:5174

// (POST /open-apis/cardkit/v1/cards) and returns the card_id.
//
// The card_id is required to drive the streaming text update path
// (PUT /open-apis/cardkit/v1/cards/{card_id}/elements/{element_id}/content).
// If this call fails the caller should fall back to inline card JSON via the
// regular Im.Message.Create path; the rich card will still render but without
// native typewriter streaming.
func (p *Platform) createCardEntity(ctx context.Context, cardJSON string) (string, error) {
	body := map[string]any{
		"type": "card_json",
		"data": cardJSON,
	}
	var apiResp *larkcore.ApiResp
	if err := p.withFreshTenantAccessTokenRetry(ctx, "create card entity", func(client *lark.Client, options ...larkcore.RequestOptionFunc) error {
		var err error
		apiResp, err = client.Post(ctx, "/open-apis/cardkit/v1/cards", body, larkcore.AccessTokenTypeTenant, options...)
		return err
	}); err != nil {
		return "", fmt.Errorf("%s: create card entity: %w", p.tag(), err)
	}
	if apiResp == nil || apiResp.StatusCode != http.StatusOK {
		return "", fmt.Errorf("%s: create card entity: HTTP status %d", p.tag(), apiResp.StatusCode)
	}
	var resp struct {
		Code int    `json:"code"`
		Msg  string `json:"msg"`
		Data struct {
			CardID string `json:"card_id"`
		} `json:"data"`
	}
	if err := json.Unmarshal(apiResp.RawBody, &resp); err != nil {
		return "", fmt.Errorf("%s: create card entity: parse response: %w", p.tag(), err)
	}
	if resp.Code != 0 {
		return "", fmt.Errorf("%s: %w", p.tag(), classifyFeishuCardAPIError("create card entity", resp.Code, resp.Msg))
	}
	if resp.Data.CardID == "" {

View on GitHub (pinned to 4000b2338a)

Solutions

1. Inspect the wrapped (%v) inner error — it names the real cause (network, auth, timeout)
2. Verify Feishu app credentials in config.toml and that the app has cardkit permissions enabled
3. Check network/DNS/proxy reachability to open.feishu.cn / open.larksuite.com
4. Increase the context timeout for streaming sends; card creation happens on the hot message path

if err := ctx.Err(); err != nil { return err } // bail before the call if already cancelled
// ensure credentials are present:
if appID == "" || appSecret == "" { return fmt.Errorf("feishu credentials missing") }

if err := p.createCardEntity(ctx, cardJSON); err != nil {
	var netErr net.Error
	if errors.As(err, &netErr) || ctx.Err() != nil {
		// transient: fall back to inline-card-JSON send
	} else {
		slog.Error("create card entity failed", "err", err)
	}
}

When it happens

Trigger: The closure passed to withFreshTenantAccessTokenRetry returns a non-nil error: HTTP transport failure, token acquisition failure inside the retry helper, or context cancellation/deadline during the POST to /open-apis/cardkit/v1/cards.

Common situations: No network access or Feishu endpoint blocked by firewall/proxy; tenant_access_token invalid or app credentials (App ID/Secret) wrong so the fresh-token retry also fails; ctx deadline exceeded on slow networks.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

• %s: stream rich card text: %w
• %s: delete preview message: %w
• redirected to unsupported image URL
• remote image host resolved to no usable IPs
• remote returned non-zero code

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