apache/cassandra · error · IllegalArgumentException

is not a field defined in this UDT

Error message

<name> is not a field defined in this UDT

What it means

UDTValue.get* methods resolve a field by name through the UDT definition's byName map. If the provided name does not match any field in the UserDefinedType definition, this IllegalArgumentException is thrown. It is a lookup failure against the UDT schema known to the driver, not a data problem.

Solutions

1. Print the actual fields with udtType.getFieldNames() and use an exact name.
2. Refresh cluster metadata (cluster.refreshSchemaMetadata()) so the driver's UDT definition matches the server after DDL changes.
3. Use the CQL-declared casing; quote names in CQL only if they were defined quoted, and pass the same string here.
4. Rebuild the session/connection so the type definition is re-fetched.

Example fix

// before
String v = udt.getString("email"); // field is 'email_address'
// after
String v = udt.getString("email_address");

if (udtType.getFieldNames().stream().noneMatch(n -> n.asInternal().equalsIgnoreCase(name))) throw new IllegalArgumentException("unknown UDT field: " + name);

try { return udt.getString(name); } catch (IllegalArgumentException e) { if (e.getMessage().endsWith("is not a field defined in this UDT")) throw new SchemaMismatchException(e); throw e; }

When it happens

Trigger: udtValue.getString("email") where the UDT defines 'email_address'; calling with a name whose case/identifier form differs after Metadata.handleId normalization; stale UDT definition after an ALTER TYPE ADD on the server.

Common situations: Schema changed on the cluster (field added/renamed) but the driver's cluster metadata was prepared earlier; case mismatch — CQL identifiers are case-insensitive unless quoted; copy-pasted field name from a different UDT.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Cannot add new field
• Cannot add new field
• Cannot drop non-frozen column
• Cannot resolve UDTs for keyspace
• Field ' ' doesn't exist in type ' .

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

Appendix: source

Thrown at src/java/org/apache/cassandra/cql3/functions/types/UDTValue.java:57

    @Override
    protected String getName(int i)
    {
        return definition.byIdx[i].getName();
    }

    @Override
    protected CodecRegistry getCodecRegistry()
    {
        return definition.getCodecRegistry();
    }

    @Override
    protected int[] getAllIndexesOf(String name)
    {
        int[] indexes = definition.byName.get(Metadata.handleId(name));
        if (indexes == null)
            throw new IllegalArgumentException(name + " is not a field defined in this UDT");
        return indexes;
    }

    /**
     * The UDT this is a value of.
     *
     * @return the UDT this is a value of.
     */
    public UserType getType()
    {
        return definition;
    }

    @Override
    public boolean equals(Object o)
    {
        if (!(o instanceof UDTValue)) return false;

View on GitHub (pinned to 88fd0f6a0e)