karatelabs/karate · error · OAuth2Exception

Token refresh failed:

Error message

Token refresh failed:

What it means

refreshToken() wraps any unexpected exception during the refresh round-trip into OAuth2Exception with the original message appended, after clearing the cached token. This is the catch-all so callers always see an OAuth2Exception with context about the token refresh that failed.

Solutions

  1. Read the wrapped cause/exception message for the root problem (the text after 'Token refresh failed: ').
  2. Verify network reachability and TLS trust to the identity provider.
  3. Check client_id/client_secret correctness — 401/400 at the token endpoint surfaces here.
  4. After fixing, re-invoke the token flow; the manager clears the bad token so the next call refreshes cleanly.
  5. ­

Example fix

// before
// message only: 'Token refresh failed: null'
// after
new OAuth2Exception(errorMessage, e); // inspect e / cause for real reason, e.g. UnknownHostException
Defensive patterns

Strategy: try-catch

Validate before calling

// preflight: network + credentials
if (!isReachable(tokenHost)) throw new Error('token endpoint unreachable'); if (!clientId || !clientSecret) throw new Error('missing client credentials');

Try / catch

try { token = mgr.refresh(); } catch (OAuth2Exception e) { Throwable cause = e.getCause(); log.error('Refresh failed: ' + e.getMessage(), cause); if (cause instanceof java.io.IOException) retryWithBackoff(); else reauthenticate(); }

Prevention

When it happens

Trigger: Any exception during token refresh other than the handled parse/shape errors: connection failures, timeouts, HTTP 4xx/5xx when the client throws, IO errors reading the body.

Common situations: IdP unreachable (DNS/firewall), client credentials rejected with 401 from the token endpoint, TLS handshake failure, network blips during long test runs.

Related errors

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/http/OAuth2TokenManager.java:109

                String errorMessage = "Token refresh failed: expected JSON object but received " +
                    (json.isArray() ? "array" : "primitive value");
                logger.error(errorMessage);
                currentToken = null;
                throw new OAuth2Exception(errorMessage);
            }

            Map<String, Object> data = json.asMap();
            OAuth2Token newToken = OAuth2Token.fromMap(data);
            storeToken(newToken);
            logger.debug("Token refreshed successfully");
            return newToken;
        } catch (OAuth2Exception e) {
            throw e;
        } catch (Exception e) {
            String errorMessage = "Token refresh failed: " + e.getMessage();
            logger.error(errorMessage);
            currentToken = null;
            throw new OAuth2Exception(errorMessage, e);
        }
    }

    /**
     * Clear stored token
     */
    public void clearToken() {
        currentToken = null;
        logger.debug("Token cleared");
    }

    /**
     * Parse OAuth error response and return a user-friendly message
     */
    private String parseOAuthError(String body, int status) {
        if (body == null || body.isBlank()) {
            return "Token refresh failed: server returned HTTP " + status + " with empty response";
        }

View on GitHub (pinned to a22eb90246)