Tencent/WeKnora · error

failed to decode JWKS document: %w

Error message

failed to decode JWKS document: %w

What it means

fetchOIDCJWKS wraps the JSON decode failure of the identity provider's JWKS document: the IdP returned 2xx but the body was not a parseable JWKS (HTML error page, truncation, wrong content type). OIDC login cannot verify id_tokens until a valid key set is fetched.

Source

Thrown at internal/application/service/user.go:1925

	req, err := http.NewRequestWithContext(ctx, http.MethodGet, jwksURI, nil)
	if err != nil {
		return nil, err
	}
	req.Header.Set("Accept", "application/json")

	resp, err := newOIDCHTTPClient().Do(req)
	if err != nil {
		return nil, err
	}
	defer func() { _ = resp.Body.Close() }()
	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
		_, _ = io.Copy(io.Discard, io.LimitReader(resp.Body, 2048))
		return nil, fmt.Errorf("JWKS request failed: status=%d", resp.StatusCode)
	}

	var jwks oidcJWKS
	if err := json.NewDecoder(io.LimitReader(resp.Body, 1<<20)).Decode(&jwks); err != nil {
		return nil, fmt.Errorf("failed to decode JWKS document: %w", err)
	}
	if len(jwks.Keys) == 0 {
		return nil, errors.New("JWKS document contains no keys")
	}
	return &jwks, nil
}

const oidcIDTokenLeeway = 2 * time.Minute

// verifyOIDCIDToken cryptographically verifies an OIDC id_token: it checks the
// RSA signature against the provider's JWKS (matched by kid) and validates the
// issuer, audience (client_id), expiry and subject. It returns the verified claims.
func (s *userService) verifyOIDCIDToken(
	ctx context.Context, cfg *config.OIDCAuthConfig, idToken string,
) (map[string]interface{}, error) {
	if strings.TrimSpace(cfg.JwksURI) == "" {
		return nil, errors.New("cannot verify OIDC id_token: no jwks_uri configured")
	}

View on GitHub (pinned to 988cbb0330)

Solutions

1. Verify jwks_uri points to the correct OIDC discovery document endpoint
2. Check the IdP is healthy and returns application/json JWKS
3. Confirm the response is under the 1MB read limit and not proxied/corrupted

When it happens

Trigger: Thrown at internal/application/service/user.go:1925 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

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