Tencent/WeKnora · error

invalid external user id: external user id too long (max %d)

Error message

invalid external user id: external user id too long (max %d)

What it means

validateExternalUserID in internal/middleware/auth.go:665 reports that the external user id exceeds maxExternalUserIDLen characters. External user IDs become part of the Principal ID ("<tenantID>:<externalID>") and are stored/logged, so their length is capped.

Source

Thrown at internal/middleware/auth.go:665

	}
	if got := principalTenantIDFromClaims(claims); got != tenantID {
		return "", fmt.Errorf("workspace mismatch: got %d want %d", got, tenantID)
	}
	sub, _ := claims["sub"].(string)
	sub = strings.TrimSpace(sub)
	if sub == "" {
		return "", errors.New("missing subject")
	}
	return sub, nil
}

func validateExternalUserID(id string) error {
	id = strings.TrimSpace(id)
	if id == "" {
		return errors.New("empty external user id")
	}
	if len(id) > maxExternalUserIDLen {
		return fmt.Errorf("external user id too long (max %d)", maxExternalUserIDLen)
	}
	for _, r := range id {
		if r < 0x20 || r == 0x7f {
			return errors.New("external user id contains invalid characters")
		}
	}
	return nil
}

func apiPrincipalAuthErrorMessage(err error) string {
	switch {
	case errors.Is(err, errMissingDirectHeader):
		return "Unauthorized: missing external user id header"
	case errors.Is(err, errInvalidExternalUserID):
		return "Unauthorized: invalid external user id"
	case errors.Is(err, errInvalidExternalUserToken):
		return "Unauthorized: invalid external user token"
	default:

View on GitHub (pinned to 988cbb0330)

Solutions

1. Shorten the external user id to within maxExternalUserIDLen (use a hash or short UUID).
2. Trim client-side and check length before sending.
3. Map long provider IDs to short internal identifiers at your identity layer.

Example fix

// before
header.Set("X-External-User-ID", longProviderNameID) // > maxExternalUserIDLen
// after
short := fmt.Sprintf("%x", sha256.Sum256([]byte(longProviderNameID)))[:32]
header.Set("X-External-User-ID", short)

id := strings.TrimSpace(externalID)
if len(id) > maxExternalUserIDLen { // hash or truncate before sending
}

func idWithinLimit(id string, max int) bool { return len(strings.TrimSpace(id)) <= max }

When it happens

Trigger: resolveAPIPrincipal (either direct-header or signed-token mode) passes an id whose length after trimming exceeds maxExternalUserIDLen.

Common situations: Using long opaque identifiers (full JWTs, long SAML nameIDs, prefixed UUID chains) as external user IDs; concatenating namespace + user id on the client.

Related errors

• principal context is required to authorize OAuth MCP service
• %w: %v
• invalid external user id: %v
• invite code has expired
• join request not found

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