quarkusio/quarkus · error · UnsupportedOperationException

Should not be called, the JSON codec is the fallback

Error message

Should not be called, the JSON codec is the fallback

What it means

Codecs contains the codec chain used to map Java values to Redis arguments. The fallback DefaultJsonCodec (used when no typed codec matches) intentionally throws UnsupportedOperationException from canHandle(Type) with this message, because canHandle must never be consulted on the fallback codec — it is chosen only after every other codec declines. Hitting this exception indicates a codec-chain implementation bug, not a user error.

Source

Thrown at extensions/redis-client/runtime/src/main/java/io/quarkus/redis/datasource/codecs/Codecs.java:67

        public JsonCodec(Type clazz) {
            if (clazz instanceof Class) {
                this.clazz = (Class<?>) clazz;
                this.type = null;
            } else {
                this.type = new TypeReference<>() {
                    @Override
                    public Type getType() {
                        return clazz;
                    }
                };
                this.clazz = null;
            }
            this.mapper = QuarkusJacksonJsonCodec.mapper();
        }

        @Override
        public boolean canHandle(Type clazz) {
            throw new UnsupportedOperationException("Should not be called, the JSON codec is the fallback");
        }

        @Override
        public byte[] encode(Object item) {
            return Json.encodeToBuffer(item).getBytes();
        }

        @Override
        public Object decode(byte[] payload) {
            try {
                if (clazz != null) {
                    return Json.decodeValue(Buffer.buffer(payload), clazz);
                } else {
                    return mapper.readValue(payload, type);
                }
            } catch (Exception e) {
                throw new RuntimeException(e);
            }

View on GitHub (pinned to e1c734241f)

Solutions

1. Do not include the default JSON codec in a canHandle-dispatch list; reserve it as the terminal fallback.
2. In dispatch loops, stop at the first codec whose canHandle returns true and use the JSON codec only when none match.
3. If you need type checks on the JSON codec, wrap it in your own codec whose canHandle inspects the Type.

Example fix

// before
for (Codec c : allCodecsIncludingJsonFallback) { if (c.canHandle(type)) ... } // throws
// after
for (Codec c : typedCodecs) { if (c.canHandle(type)) return c; }
return jsonFallbackCodec; // never call canHandle on it

if (codec instanceof DefaultJsonCodec) {
    // never ask canHandle on the JSON fallback; use it only when nothing else matches
    throw new IllegalStateException("JSON fallback codec must be terminal in the dispatch chain");
}

boolean isJsonFallback(io.quarkus.redis.datasource.codecs.Codec c) { return c != null && c.getClass().getSimpleName().contains("DefaultJson"); }

try { handled = candidate.canHandle(type); } catch (UnsupportedOperationException e) { // fallback codec reached in dispatch — treat as 'no match' and use it directly
  return candidate; }

When it happens

Trigger: Registering the JSON fallback codec explicitly in a codec list so canHandle is called on it, or custom codec-dispatch code that iterates all codecs (including the fallback) calling canHandle, rather than using the fallback only as a last resort.

Common situations: Custom serialization frameworks or wrapper libraries re-implementing codec dispatch and calling canHandle on every registered codec; version changes in quarkus-redis-client altering the codec contract; unit tests invoking canHandle directly.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• The Reactive Redis Client must be injected
• Not Allowed
• Printing is not supported with Quarkus AWT extension.
• Stateless operations not supported
• Managed operations not supported

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