What causes "embed visitor id too long (max 128)" in Tencent/WeKnora?

Issue shorter visitor IDs on the embed client side

embed visitor id too long (max 128)

Error message

embed visitor id too long (max 128)

What it means

Guard error in ValidateEmbedVisitorID: the client-supplied anonymous embed visitor ID is non-empty but longer than 128 bytes, so ensureEmbedSession refuses to build an embed visitor principal from it. The limit bounds the Principal ID string size.

Solutions

Issue shorter visitor IDs on the embed client side
Trim or hash overly long client-supplied visitor IDs before validation

Example fix

// before
visitorID := jwtToken // hundreds of bytes
// after
visitorID := uuid.NewString() // 36 chars, well under 128

Defensive patterns

Strategy: validation

Validate before calling

if len(visitorID) > 128 { visitorID = visitorID[:128] } // or regenerate
if len(visitorID) == 0 { visitorID = uuid.NewString() }

Type guard

func visitorIDLengthOK(id string) bool { return len(id) > 0 && len(id) <= 128 }

Try / catch

if err := ValidateEmbedVisitorID(id); err != nil {
    if strings.Contains(err.Error(), "too long") {
        id = uuid.NewString() // replace oversized id
    }
}

Prevention

Use UUIDs (36 chars) as visitor ids, never tokens or concatenated values
Check byte length (len), not rune count, before sending
Keep token-like credentials out of the visitor id field

When it happens

Trigger: Calling ensureEmbedSession with a visitor id whose length exceeds 128 bytes — e.g. an over-long generated token, concatenated identifiers, or a JWT/prefixed value stuffed into the visitor id field.

Common situations: Frontend storing a full session token or telemetry id instead of a short UUID in the visitor id slot; id built by concatenating multiple ids or timestamps; base64 blobs copied from other systems.

Related errors

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

Appendix: source

Thrown at internal/types/principal.go:132

	}
}

// EmbedVisitorPrincipal identifies one anonymous embed visitor (browser).
func EmbedVisitorPrincipal(tenantID uint64, channelID, visitorID string) Principal {
	return Principal{
		Type: PrincipalEmbedVisitor,
		ID:   fmt.Sprintf("%d:%s:%s", tenantID, strings.TrimSpace(channelID), strings.TrimSpace(visitorID)),
	}
}

// ValidateEmbedVisitorID checks the client-supplied anonymous visitor id.
func ValidateEmbedVisitorID(id string) error {
	id = strings.TrimSpace(id)
	if id == "" {
		return fmt.Errorf("empty embed visitor id")
	}
	if len(id) > 128 {
		return fmt.Errorf("embed visitor id too long (max 128)")
	}
	for _, r := range id {
		if r < 0x20 || r == 0x7f {
			return fmt.Errorf("embed visitor id contains invalid characters")
		}
	}
	return nil
}

// MCPOAuthPrincipalFromContext resolves the OAuth token principal for ctx.
// Embed chat sessions map to a per-visitor principal when X-Embed-Visitor is
// present; otherwise OAuth falls back to the chat session principal.
func MCPOAuthPrincipalFromContext(ctx context.Context) Principal {
	p, ok := PrincipalFromContext(ctx)
	if !ok {
		return Principal{}
	}
	p = p.Normalize()

View on GitHub (pinned to 988cbb0330)