jwtk/jjwt · error · IllegalArgumentException

Unable to convert String value

Error message

Unable to convert String value '${s}' to URI instance: ${e.getMessage()}

What it means

UriStringConverter.applyFrom converts a CharSequence to a java.net.URI via URI.create, first asserting it has text. If URI.create throws (IllegalArgumentException due to invalid URI syntax, etc.), the converter wraps it in an IllegalArgumentException including the original string and the cause message.

Solutions

Ensure the string is a syntactically valid absolute URI: scheme://host/path with illegal characters percent-encoded.
Encode query/path parameters with URLEncoder/UriComponentsBuilder before composing the URL.
Validate with URI.create(...) yourself in a try/catch to surface a clearer message before calling the API.

Example fix

// before
jwtBuilder.claim("jku", "https://example.com/my keys/jwks.json");
// after
jwtBuilder.claim("jku", "https://example.com/my%20keys/jwks.json");

Defensive patterns

Strategy: validation

Validate before calling

URI safeUri(String s) {
    if (s == null || s.isBlank()) throw new IllegalArgumentException("URI string cannot be null or empty.");
    try {
        return URI.create(s);
    } catch (IllegalArgumentException e) {
        throw new IllegalArgumentException("Invalid URI: '" + s + "'", e);
    }
}

Try / catch

try {
    converter.applyFrom(raw);
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Unable to convert String value")) {
        // inspect the raw string for spaces/illegal chars/missing scheme
    }
    throw e;
}

Prevention

Percent-encode spaces and special characters in URLs before setting URI claims
Always include an explicit scheme (https://)
Validate configuration-provided URLs at startup with URI.create

When it happens

Trigger: Setting a URI-typed claim (e.g. 'jwk' URLs, 'iss' values converted via this converter, OIDC discovery URLs) with a syntactically invalid string containing spaces, illegal characters, or unmatched brackets.

Common situations: Unencoded spaces or non-ASCII characters in URLs; building URLs by string concatenation with missing scheme ('example.com/x' instead of 'https://example.com/x'); config values with trailing whitespace or quotes.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

AI-assisted analysis of jwtk/jjwt@fb71496164 (2026-09-09). Data as JSON: /api/errors/5f13e05526121f43. Report an issue: GitHub.

Appendix: source

Thrown at impl/src/main/java/io/jsonwebtoken/impl/lang/UriStringConverter.java:37

import java.net.URI;

public class UriStringConverter implements Converter<URI, CharSequence> {

    @Override
    public String applyTo(URI uri) {
        Assert.notNull(uri, "URI cannot be null.");
        return uri.toString();
    }

    @Override
    public URI applyFrom(CharSequence s) {
        Assert.hasText(s, "URI string cannot be null or empty.");
        try {
            return URI.create(s.toString());
        } catch (Exception e) {
            String msg = "Unable to convert String value '" + s + "' to URI instance: " + e.getMessage();
            throw new IllegalArgumentException(msg, e);
        }
    }
}

View on GitHub (pinned to fb71496164)