Tencent/WeKnora · error

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.

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)

Solutions

1. Issue shorter visitor IDs on the embed client side
2. 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

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

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

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

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

• empty embed visitor id
• embed visitor id contains invalid characters
• model ID cannot be empty
• unknown credential field:
• member_limit must be >= 0

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