quarkusio/quarkus · error · IllegalArgumentException

invalid Character value:

Error message

invalid Character value: 

What it means

CharacterParamConverter.convert throws an IllegalArgumentException when a parameter mapped to java.lang.Character is not a single-character string. Identical to the primitive char converter but for the wrapper type. Malformed values surface as request failures (400).

Source

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

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

public class CharacterParamConverter implements ParameterConverter {

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

    public static class Supplier implements ParameterConverterSupplier {

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

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

View on GitHub (pinned to e1c734241f)

Solutions

1. Ensure the client sends exactly one character, e.g. ?mode=a not ?mode=abc.
2. Change the parameter to String and perform explicit validation with a friendly error.
3. Trim or validate input client-side; reject empty strings before submission.
4. Use a proper enum or boolean instead of a single-character code for clarity.

Example fix

// before
// request: GET /items?grade=AB
public Response list(@QueryParam("grade") Character grade) // throws
// after
// request: GET /items?grade=A
public Response list(@QueryParam("grade") Character grade)

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

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

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

When it happens

Trigger: A @QueryParam/@PathParam/@HeaderParam/@RestForm Character parameter receives "", a multi-character string, or an unparsable value from the request.

Common situations: Empty query parameters; clients sending words where a single flag letter is expected; API changes where the parameter became longer; typos like "ab" for a mode flag.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• invalid char value: " + str
• 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/19833cf623c93210. Report an issue: GitHub.