karatelabs/karate · info · OAuth2Exception

URL encoding failed

Error message

URL encoding failed

What it means

This error is thrown by AuthorizationCodeAuthHandler.urlEncode when URLEncoder.encode fails with an UnsupportedEncodingException. Because the encoding is fixed to UTF-8 (which the JVM is required to support), this should never happen in practice; it exists to satisfy checked-exception handling. It is wrapped in an OAuth2Exception with the message 'URL encoding failed'.

Solutions

1. Verify the JVM is a standard, up-to-date OpenJDK/Oracle build; replace non-standard JVMs
2. Upgrade to a JDK where 'UTF-8' is a guaranteed supported encoding (all compliant JDKs)
3. If it persists, check for custom CharsetProvider implementations or shaded jars that broke java.nio.charset init
4. As a workaround, catch OAuth2Exception around the auth-URL build and log the wrapped cause

Example fix

// before: running on a custom/minimal JVM
java -custom-jvm ... 
// after: use a standard JDK
java -version  # OpenJDK 11+; rerun the OAuth2 flow

// UTF-8 is guaranteed on compliant JVMs; nothing meaningful to pre-check
if (!java.nio.charset.Charset.isSupported("UTF-8")) { throw new IllegalStateException("broken JVM: UTF-8 unsupported"); }

try { auth.buildAuthorizationUrl(...); } catch (OAuth2Exception e) { log.error("oauth url build failed", e.getCause()); }

When it happens

Trigger: Calling buildAuthorizationUrl (which invokes urlEncode on the client_id, redirect_uri, scope, and state values) in a JVM environment where StandardCharsets.UTF_8.toString() resolves to an unsupported encoding name — effectively only possible with a broken/custom charset provider or non-compliant JVM.

Common situations: Practically never hit by end users; occasionally reported on exotic or misconfigured JVMs, custom classloading setups where the charset provider is broken, or shade/relocation mistakes that corrupt charset initialization.

Related errors

• Failed to generate code challenge
• failed to start debug server
• Authorization flow failed: " + e.getMessage()
• Missing 'authorizationUrl' in OAuth config
• Missing 'client_id' in OAuth config

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

Appendix: source

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

                } catch (NumberFormatException e) {
                    throw new OAuth2Exception("Invalid port in callbackPorts: " + parts[i]);
                }
            }
            return ports;
        }
        throw new OAuth2Exception("Invalid callbackPorts type: " + portsValue.getClass());
    }

    private String generateState() {
        // Simple state generation - could be more sophisticated
        return java.util.UUID.randomUUID().toString();
    }

    private String urlEncode(String value) {
        try {
            return URLEncoder.encode(value, StandardCharsets.UTF_8.toString());
        } catch (UnsupportedEncodingException e) {
            throw new OAuth2Exception("URL encoding failed", e);
        }
    }

    private String truncate(String value) {
        if (value == null) {
            return "(empty)";
        }
        if (value.length() <= 100) {
            return value;
        }
        return value.substring(0, 100) + "...";
    }

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

View on GitHub (pinned to a22eb90246)