Tencent/WeKnora · error

failed to persist authorization state: %w

Error message

failed to persist authorization state: %w

What it means

Returned by StartAuthorization when m.states.Put fails to persist the OAuthState (tenant, principal, service, PKCE verifier) keyed by the state token. The callback later could not be matched to this flow, so starting authorization is aborted to avoid an unrecoverable half-started flow.

Source

Thrown at internal/mcp/oauth_manager.go:147

		return "", "", fmt.Errorf("failed to generate state: %w", err)
	}

	authURL, err := h.GetAuthorizationURL(ctx, state, challenge)
	if err != nil {
		return "", "", fmt.Errorf("failed to build authorization URL: %w", err)
	}

	if err := m.states.Put(ctx, state, OAuthState{
		TenantID:         tenantID,
		UserID:           principal.StorageID(),
		Principal:        principal,
		ServiceID:        service.ID,
		CodeVerifier:     verifier,
		ClientID:         h.GetClientID(),
		RedirectURI:      redirectURI,
		FrontendRedirect: frontendRedirect,
	}); err != nil {
		return "", "", fmt.Errorf("failed to persist authorization state: %w", err)
	}

	return authURL, state, nil
}

// StartAuthorizationForService loads the MCP service by ID and starts the
// authorization-code flow, returning the URL the user must open. It is a
// convenience for callers (e.g. IM channels) that only hold a service ID and
// cannot reach the MCP service lookup directly.
func (m *OAuthManager) StartAuthorizationForService(
	ctx context.Context,
	tenantID uint64,
	principal types.Principal,
	serviceID, redirectURI, frontendRedirect string,
) (string, error) {
	service, err := m.serviceRepo.GetByID(ctx, tenantID, serviceID)
	if err != nil {
		return "", fmt.Errorf("failed to load MCP service: %w", err)

View on GitHub (pinned to 988cbb0330)

Solutions

1. Inspect the wrapped error — usually a backend store outage or timeout
2. Check the OAuth state store's connectivity and TTL configuration
3. Retry the authorization start once the store recovers

When it happens

Trigger: Thrown at internal/mcp/oauth_manager.go:147 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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