Tencent/WeKnora · error

empty embed visitor id

Error message

empty embed visitor id

What it means

ValidateEmbedVisitorID rejects an empty (or whitespace-only) client-supplied anonymous visitor id. The embed session bootstrap (ensureEmbedSession) requires a non-empty visitor id to associate the session with an anonymous user, so it fails fast with this error.

Source

Thrown at internal/types/principal.go:129

	return Principal{
		Type: PrincipalEmbedSession,
		ID:   fmt.Sprintf("%d:%s:%s", tenantID, strings.TrimSpace(channelID), strings.TrimSpace(sessionID)),
	}
}

// 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 {

View on GitHub (pinned to 988cbb0330)

Solutions

1. Generate and send a non-empty visitor id (e.g. a UUID) with the embed session request
2. Check the embed client actually persists/reads the visitor id before calling the API
3. Trim/verify the value client-side; if empty, generate a fresh id instead of sending a blank string
4. Inspect the request payload/headers to confirm the visitor id field is populated

Example fix

// before
visitorID := ""
ensureEmbedSession(visitorID)
// after
visitorID := existingOrNewUUID()
if strings.TrimSpace(visitorID) == "" { visitorID = uuid.NewString() }
ensureEmbedSession(visitorID)

func hasVisitorID(id string) bool { return strings.TrimSpace(id) != "" }
if !hasVisitorID(visitorID) { visitorID = uuid.NewString() }

func isNonEmptyTrimmed(s string) bool { return strings.TrimSpace(s) != "" }

if err := ValidateEmbedVisitorID(id); err != nil {
    if strings.Contains(err.Error(), "empty embed visitor id") {
        id = uuid.NewString() // regenerate and retry
    }
}

When it happens

Trigger: Calling ensureEmbedSession (directly or via the embed endpoint) without supplying a visitor id, or supplying one that is only whitespace, causing TrimSpace to yield "".

Common situations: Embed frontend not persisting/generating the visitor id cookie or localStorage key before the first API call, a cleared browser storage, or an API client omitting the visitor id header/field entirely.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• embed visitor id too long (max 128)
• 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/792e92eaf364bd2e. Report an issue: GitHub.