What causes "client credentials auth request failed: " + e.getMessage()" in karatelabs/karate?

Check the token endpoint URL configured on the handler is correct and reachable (curl it)

karatelabs/karate · error · RuntimeException

client credentials auth request failed: " + e.getMessage()

Error message

client credentials auth request failed: " + e.getMessage()

What it means

ClientCredentialsAuthHandler.requestToken POSTs the client-credentials token request and parses the JSON response. Any exception during the HTTP call or JSON parsing is logged and rethrown as a RuntimeException with message 'client credentials auth request failed: <detail>'. It wraps the original exception as the cause.

Solutions

Check the token endpoint URL configured on the handler is correct and reachable (curl it)
Verify client_id/client_secret are valid — an auth server often returns HTML/JSON error bodies that fail parsing
Inspect the wrapped cause (e.getCause()) and the logged 'client credentials auth request failed' detail
Confirm network/proxy/TLS settings allow outbound POST to the auth server

Defensive patterns

Strategy: retry

Validate before calling

// before wiring the handler, verify the endpoint responds
// curl -s -o /dev/null -w '%{http_code}' -X POST -d 'grant_type=client_credentials' $TOKEN_URL

Try / catch

try { handler.apply(builder); } catch (RuntimeException e) { log.error("token request failed: {} / {}", e.getMessage(), e.getCause()); }

Prevention

Validate the token endpoint URL and credentials with curl before runtime
Configure sane connect/read timeouts and a bounded retry with backoff
Check the auth server returns application/json; an HTML error page will fail parsing
Monitor cause chains (TLS, DNS, proxy) when failures occur

When it happens

Trigger: Calling apply(builder) on a ClientCredentialsAuthHandler when: the token endpoint URL is wrong or unreachable, the connection fails or times out, the server returns a non-JSON body, or Json.of(...) cannot parse the response.

Common situations: Misconfigured tokenUrl, network/DNS failures, OAuth server returning an error page (HTML) instead of JSON for bad client_id/secret, TLS certificate problems, proxy blocking the outbound call.

Related errors

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/http/ClientCredentialsAuthHandler.java:55

                    logger.warn("failed to parse main request URL for relative token URL resolution: {}", e.getMessage());
                }
            }
        }

        builder.url(tokenUrl);
        builder.formField("grant_type", "client_credentials");
        builder.formField("client_id", config.get("client_id"));
        builder.formField("client_secret", config.get("client_secret"));
        if (config.containsKey("scope")) {
            builder.formField("scope", config.get("scope"));
        }
        builder.header("Accept", "application/json");
        try {
            HttpResponse response = builder.invoke("post");
            return Json.of(response.getBodyString()).asMap();
        } catch (Exception e) {
            logger.error("client credentials auth request failed: {}", e.getMessage());
            throw new RuntimeException("client credentials auth request failed: " + e.getMessage(), e);
        }
    }

    @Override
    public void apply(HttpRequestBuilder builder) {
        if (token == null) {
            token = requestToken(builder.forkNewBuilder(), config, builder.getUrl());
        }
        builder.header("Authorization", "Bearer " + token.get("access_token"));
    }

    @Override
    public String getType() {
        return "oauth2";
    }

    @Override
    public String toCurlPreview(String platform) {

View on GitHub (pinned to a22eb90246)