{"record":{"id":"ab725c33e58d7946","repo":"karatelabs/karate","slug":"url-encoding-failed","errorCode":null,"errorMessage":"URL encoding failed","messagePattern":"URL encoding failed","errorType":"exception","errorClass":"OAuth2Exception","httpStatus":null,"severity":"info","filePath":"karate-core/src/main/java/io/karatelabs/http/AuthorizationCodeAuthHandler.java","lineNumber":316,"sourceCode":"                } catch (NumberFormatException e) {\n                    throw new OAuth2Exception(\"Invalid port in callbackPorts: \" + parts[i]);\n                }\n            }\n            return ports;\n        }\n        throw new OAuth2Exception(\"Invalid callbackPorts type: \" + portsValue.getClass());\n    }\n\n    private String generateState() {\n        // Simple state generation - could be more sophisticated\n        return java.util.UUID.randomUUID().toString();\n    }\n\n    private String urlEncode(String value) {\n        try {\n            return URLEncoder.encode(value, StandardCharsets.UTF_8.toString());\n        } catch (UnsupportedEncodingException e) {\n            throw new OAuth2Exception(\"URL encoding failed\", e);\n        }\n    }\n\n    private String truncate(String value) {\n        if (value == null) {\n            return \"(empty)\";\n        }\n        if (value.length() <= 100) {\n            return value;\n        }\n        return value.substring(0, 100) + \"...\";\n    }\n\n    @Override\n    public String getType() {\n        return \"oauth2\";\n    }\n","sourceCodeStart":298,"sourceCodeEnd":334,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-core/src/main/java/io/karatelabs/http/AuthorizationCodeAuthHandler.java#L298-L334","documentation":"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'.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the JVM is a standard, up-to-date OpenJDK/Oracle build; replace non-standard JVMs","Upgrade to a JDK where 'UTF-8' is a guaranteed supported encoding (all compliant JDKs)","If it persists, check for custom CharsetProvider implementations or shaded jars that broke java.nio.charset init","As a workaround, catch OAuth2Exception around the auth-URL build and log the wrapped cause"],"exampleFix":"// before: running on a custom/minimal JVM\njava -custom-jvm ... \n// after: use a standard JDK\njava -version  # OpenJDK 11+; rerun the OAuth2 flow","handlingStrategy":"try-catch","validationCode":"// UTF-8 is guaranteed on compliant JVMs; nothing meaningful to pre-check\nif (!java.nio.charset.Charset.isSupported(\"UTF-8\")) { throw new IllegalStateException(\"broken JVM: UTF-8 unsupported\"); }","typeGuard":null,"tryCatchPattern":"try { auth.buildAuthorizationUrl(...); } catch (OAuth2Exception e) { log.error(\"oauth url build failed\", e.getCause()); }","preventionTips":["Run on a standard, current OpenJDK build","Avoid custom CharsetProviders and unusual shading setups","Keep the wrapped cause in logs to diagnose exotic environments"],"tags":["oauth2","encoding","url-encoding","jvm"],"backgroundTag":"oauth-token-exchange-failed","analyzedSha":"a22eb90246d958d15a47bf436693d0121ad2812d","analyzedAt":"2026-09-12T09:01:00.220Z","contentChangedAt":"2026-09-12T09:01:00.220Z","schemaVersion":2},"datasetVersion":"2026-09-16T19:17:19.609Z"}