chenhg5/cc-connect · warning

%s: create card entity: empty card_id in response

Error message

%s: create card entity: empty card_id in response

What it means

Cardkit returned HTTP 200, code==0 (success), but the data.card_id field is empty. The card_id is mandatory for the subsequent PUT element-content streaming calls, so a success response without it is treated as a contract violation by the API.

Source

Thrown at platform/feishu/feishu.go:5193

	}
	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 == "" {
		return "", fmt.Errorf("%s: create card entity: empty card_id in response", p.tag())
	}
	return resp.Data.CardID, nil
}

// StreamRichCardText implements core.RichCardTextStreamer. Pushes the latest
// fullText to the rich card's main_text element via cardkit-v1 streaming text
// update API. The Lark client renders the increment between consecutive PUTs
// with a typewriter animation (controlled by the card's streaming_config).
//
// Returns ErrNotSupported when the handle has no cardID (preview was created
// via the inline-card-JSON fallback path; engine should fall back to full-card
// Patch).
func (p *Platform) StreamRichCardText(ctx context.Context, previewHandle any, fullText string) error {
	h, ok := previewHandle.(*feishuPreviewHandle)
	if !ok {
		return fmt.Errorf("%s: StreamRichCardText: invalid preview handle type %T", p.tag(), previewHandle)
	}

View on GitHub (pinned to 4000b2338a)

Solutions

  1. Log the raw response body to see where the card_id actually lives
  2. Update the inline response struct if Feishu moved/renamed the card_id field
  3. Upgrade the larksuite SDK / pin to the documented Cardkit v1 endpoint
  4. Treat as fallback signal: proceed with inline-card-JSON send instead of the streaming path

Example fix

// before
Data struct {
	CardID string `json:"card_id"`
} `json:"data"`
// after
Data struct {
	CardID string `json:"card_id"`
} `json:"data"`
// plus logging on the empty path:
if resp.Data.CardID == "" {
	slog.Warn(p.tag()+": create card entity: empty card_id", "raw", string(apiResp.RawBody))
	return "", fmt.Errorf("%s: create card entity: empty card_id in response", p.tag())
}
Defensive patterns

Strategy: fallback

Validate before calling

var probe struct{ Data struct{ CardID string `json:"card_id"` } `json:"data"` }
_ = json.Unmarshal(apiResp.RawBody, &probe)
if probe.Data.CardID == "" {
	// use inline-card-JSON path instead of streaming
}

Type guard

func hasCardID(raw []byte) bool {
	var r struct { Data struct { CardID string `json:"card_id"` } `json:"data"` }
	return json.Unmarshal(raw, &r) == nil && r.Data.CardID != ""
}

Try / catch

cardID, err := p.createCardEntity(ctx, cardJSON)
if err != nil || cardID == "" {
	// engine falls back to inline-card-JSON (handle.CardID empty → ErrNotSupported from StreamRichCardText)
}

Prevention

When it happens

Trigger: POST /open-apis/cardkit/v1/cards succeeds but the JSON body omits card_id or nests it differently than the struct expects (data.card_id), e.g. an API version change or a new Cardkit entity type whose response carries the ID elsewhere.

Common situations: Feishu API schema drift between documented and actual response; SDK/endpoint returning an envelope where data is null on some entity types; region-specific (larksuite vs feishu) response differences.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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