quarkusio/quarkus · error · IllegalArgumentException

invalid char value: " + str

Error message

invalid char value: " + str

What it means

CharParamConverter.convert throws an IllegalArgumentException when converting a request parameter to a primitive char if the raw string does not contain exactly one character. Parameter converters translate string query/path/form/header values; only a 1-character string is a valid char. The exception typically surfaces as a 400 response.

Source

Thrown at independent-projects/resteasy-reactive/server/runtime/src/main/java/org/jboss/resteasy/reactive/server/core/parameters/converters/CharParamConverter.java:9

package org.jboss.resteasy.reactive.server.core.parameters.converters;

public class CharParamConverter implements ParameterConverter {

    @Override
    public Object convert(Object parameter) {
        String str = parameter.toString();
        if (str.length() != 1) {
            throw new IllegalArgumentException("invalid char value: " + str);
        }
        return str.charAt(0);
    }

    public static class Supplier implements ParameterConverterSupplier {

        @Override
        public String getClassName() {
            return CharParamConverter.class.getName();
        }

        @Override
        public CharParamConverter get() {
            return new CharParamConverter();
        }
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

1. Send exactly one character for the parameter, or change the endpoint type to String and validate manually with a clear error message.
2. Use Character (wrapper) with an explicit null/length check if absence must be handled gracefully.
3. Add client-side validation enforcing max length 1 before the request.
4. If values can be legitimately longer, refactor the resource to String/enum.

Example fix

// before
public Response get(@QueryParam("initial") char initial)
// after
public Response get(@QueryParam("initial") String initial) {
    if (initial == null || initial.length() != 1) throw new BadRequestException("initial must be a single char");
    char c = initial.charAt(0); ...
}

if (raw == null || raw.length() != 1) { throw new BadRequestException("'initial' must be exactly one character"); }

boolean isSingleChar(String s) { return s != null && s.length() == 1; }

try { char c = (char) converter.convert(raw); } catch (IllegalArgumentException e) { return Response.status(400).entity(e.getMessage()).build(); }

When it happens

Trigger: A query/path/header/form parameter mapped to a char receives an empty string or a string longer than one character, e.g. ?letter=ab or a missing-but-empty param.

Common situations: Clients sending multi-character values by mistake; empty query params (?x=); locale/data-entry issues; APIs where a 'code' field grew from one character to more.

Related errors

• invalid Character value:
• Extra steps left over
• Unknown start character for json value: %s
• Before and after name lengths do not match
• Currently only 'fruitsFindBy?type=name' is supported

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/ce85ad2d0735dc22. Report an issue: GitHub.