karatelabs/karate · error · OAuth2Exception

Authorization flow failed: " + e.getMessage()

Error message

Authorization flow failed: " + e.getMessage()

What it means

performAuthorizationFlow() runs the full OAuth2 authorization-code + PKCE flow: open browser, wait for the callback, exchange the code, store the token. Any exception inside the flow (browser failed to open, user cancelled, callback timeout, token exchange HTTP error) is caught, logged, and rethrown as an OAuth2Exception wrapping the original message; the local callback server is stopped in finally.

Solutions

  1. Read the wrapped cause (getMessage() plus getCause()) to identify the failing stage
  2. Verify authorizationUrl, token url, client_id and redirect_uri against the provider's app registration
  3. Confirm the provider is reachable and the callback port is free
  4. Increase the callback wait timeout and retry the flow

Example fix

// before
config.put("redirect_uri", "http://localhost:8080/callback"); // not registered
// after
config.put("redirect_uri", "http://localhost:5177/callback"); // matches registered redirect
Defensive patterns

Strategy: try-catch

Validate before calling

// pre-flight config check before starting the flow
if (config.get("authorizationUrl") == null || config.get("client_id") == null
    || config.get("url") == null || config.get("redirect_uri") == null) {
    throw new IllegalArgumentException("Incomplete OAuth config");
}

Try / catch

try {
    Token t = handler.apply(request);
} catch (OAuth2Exception e) {
    if (e.getMessage().startsWith("Authorization flow failed")) {
        logger.warn("OAuth flow failed: {} cause={}", e.getMessage(), e.getCause());
        // inspect cause: callback timeout vs token exchange HTTP error
    } else { throw e; }
}

Prevention

When it happens

Trigger: Any failure inside apply() -> performAuthorizationFlow(): the token endpoint rejects the code exchange, the callback server never receives a redirect, PKCE verification fails, or the authorization page errors.

Common situations: Wrong token endpoint URL or client secret, redirect_uri mismatch with the provider's registered redirect, provider downtime, or the user taking longer than the callback timeout to authenticate.

Related errors

AI-assisted analysis of karatelabs/karate@a22eb90246 (2026-09-12). Data as JSON: /api/errors/a6f0d383701178d2. Report an issue: GitHub.

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/http/AuthorizationCodeAuthHandler.java:120

            logger.debug("Authorization code received");

            // 5. Exchange code for token
            OAuth2Token token = exchangeCodeForToken(
                builder.forkNewBuilder(),
                code,
                pkce.getVerifier(),
                redirectUri
            );

            // 6. Store token
            tokenManager.storeToken(token);

            return token;

        } catch (Exception e) {
            logger.error("Authorization flow failed: {}", e.getMessage());
            throw new OAuth2Exception("Authorization flow failed: " + e.getMessage(), e);
        } finally {
            if (callbackServer != null) {
                callbackServer.stop();
            }
        }
    }

    /**
     * Build authorization URL with all required parameters
     */
    private String buildAuthorizationUrl(PkceGenerator pkce, String redirectUri) {
        String authzEndpoint = (String) config.get("authorizationUrl");
        if (authzEndpoint == null) {
            throw new OAuth2Exception("Missing 'authorizationUrl' in OAuth config");
        }

        String clientId = (String) config.get("client_id");
        if (clientId == null) {

View on GitHub (pinned to a22eb90246)