apache/cassandra · error · CodecNotFoundException

Codec not found for requested operation

Error message

Codec not found for requested operation: [%s <-> %s]

What it means

CodecRegistry.createCodec(DataType, TypeToken) throws this when it cannot build a TypeCodec for the requested CQL type / Java type pair: either maybeCreateCodec returned null, or the freshly built codec fails the double-check codec.accepts(cqlType)/accepts(javaType). The double-check commonly fails for collections whose element Java type is a subclass of what the registry can serve.

Solutions

1. Register a custom TypeCodec via CodecRegistry.getInstance().register(codec) covering the exact DataType/JavaType pair.
2. For collections, register an ElementCodec-based collection codec (e.g. TypeCodec.listOf(elementCodec)) so element mapping is explicit.
3. Verify the Java generic type matches the CQL type (e.g. List<Integer> for list<int>, not List<Integer> vs list<varint> surprises like BigInteger).

Example fix

// before
TypeCodec<List<MyPojo>> c = registry.codecFor(cluster.getMetadata().newTupleType(...), new TypeToken<List<MyPojo>>(){});
// after
registry.register(new MappingCodec<>(TypeCodec.listOf(udtCodec), new TypeToken<List<MyPojo>>(){}));

if (!registry.codecFor(cqlType).accepts(javaType)) System.err.println("no codec for " + cqlType + " <-> " + javaType);

boolean hasCodec(CodecRegistry r, DataType t, TypeToken<?> jt) { try { r.codecFor(t, jt); return true; } catch (Exception e) { return false; } }

try { TypeCodec<T> c = registry.codecFor(cqlType, javaType); ... } catch (InvalidTypeException | CodecNotFoundException e) { registerFallbackCodec(cqlType, javaType); }

When it happens

Trigger: Calling codecRegistry.codecFor(cqlType, javaType) (or getCodec) with a type pair no registered codec accepts, e.g. a custom Java type with no registered codec, or a List<SubType> request where only a codec for List<BaseType> exists and the resulting codec fails the accepts() re-validation.

Common situations: Mapping a UDT or collection to a custom POJO without registering a codec; upgrading driver versions where type-token generics changed; requesting codecs for nested collections (map<text, list<udt>>) mapped to custom classes.

Related errors

• Ignoring codec because it collides with previously…
• Ignoring codec because it collides with previously…
• Invalid 32-bits integer value, expecting 4 bytes but got
• Invalid type for map key, expecting
• Map keys cannot be null

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/7ce390d3f5d23833. Report an issue: GitHub.

Appendix: source

Thrown at src/java/org/apache/cassandra/cql3/functions/types/CodecRegistry.java:724

            }
        }

        // Look at the user-registered codecs next
        for (TypeCodec<?> codec : codecs)
        {
            if ((cqlType == null || codec.accepts(cqlType)) && codec.accepts(value))
            {
                logger.trace("Already registered codec found: {}", codec);
                return (TypeCodec<T>) codec;
            }
        }
        return createCodec(cqlType, value);
    }

    private <T> TypeCodec<T> createCodec(DataType cqlType, TypeToken<T> javaType)
    {
        TypeCodec<T> codec = maybeCreateCodec(cqlType, javaType);
        if (codec == null) throw notFound(cqlType, javaType);
        // double-check that the created codec satisfies the initial request
        // this check can fail specially when creating codecs for collections
        // e.g. if B extends A and there is a codec registered for A and
        // we request a codec for List<B>, the registry would generate a codec for List<A>
        if (!codec.accepts(cqlType) || (javaType != null && !codec.accepts(javaType)))
            throw notFound(cqlType, javaType);
        logger.trace("Codec created: {}", codec);
        return codec;
    }

    private <T> TypeCodec<T> createCodec(DataType cqlType, T value)
    {
        TypeCodec<T> codec = maybeCreateCodec(cqlType, value);
        if (codec == null) throw notFound(cqlType, TypeToken.of(value.getClass()));
        // double-check that the created codec satisfies the initial request
        if ((cqlType != null && !codec.accepts(cqlType)) || !codec.accepts(value))
            throw notFound(cqlType, TypeToken.of(value.getClass()));
        logger.trace("Codec created: {}", codec);

View on GitHub (pinned to 88fd0f6a0e)