apache/cassandra · error · ConfigurationException

Cannot resolve UDTs for keyspace %s: some types are missing

Error message

Cannot resolve UDTs for keyspace %s: some types are missing

What it means

Thrown as a ConfigurationException when Types.build performs topological resolution of UDT definitions for a keyspace and the resolved set is smaller than the declared definitions, meaning one or more referenced types could not be resolved. This typically means a UDT references another type that is undefined or unresolvable due to a dependency cycle.

Source

Thrown at src/java/org/apache/cassandra/schema/Types.java:378

            for (Map.Entry<RawUDT, Integer> entry : vertices.entrySet())
                if (entry.getValue() == 0)
                    resolvableTypes.add(entry.getKey());

            Types types = new Types(new HashMap<>());
            while (!resolvableTypes.isEmpty())
            {
                RawUDT vertex = resolvableTypes.remove();

                for (RawUDT dependentType : adjacencyList.get(vertex))
                    if (vertices.replace(dependentType, vertices.get(dependentType) - 1) == 1)
                        resolvableTypes.add(dependentType);

                UserType udt = vertex.prepare(keyspace, types);
                types.types.put(udt.name, udt);
            }

            if (types.types.size() != definitions.size())
                throw new ConfigurationException(format("Cannot resolve UDTs for keyspace %s: some types are missing", keyspace));

            /*
             * return an immutable copy
             */
            return Types.builder().add(types).build();
        }

        public void add(String name, List<String> fieldNames, List<String> fieldTypes)
        {
            add(name, fieldNames, fieldTypes, EMPTY_COMMENT, EMPTY_SECURITY_LABEL, EMPTY_FIELD_COMMENTS, EMPTY_FIELD_SECURITY_LABELS);
        }

        public void add(String name, List<String> fieldNames, List<String> fieldTypes, String comment, String securityLabel)
        {
            add(name, fieldNames, fieldTypes, comment, securityLabel, EMPTY_FIELD_COMMENTS, EMPTY_FIELD_SECURITY_LABELS);
        }

        public void add(String name,

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Inspect system_schema.types for the keyspace and find definitions referencing non-existent types
Drop and recreate the broken UDTs in dependency order (leaf types first)
Restore complete type definitions from a valid schema snapshot
Manually delete the unresolvable rows from system_schema.types (with care) so the keyspace can load

Example fix

// before (schema contains address -> fullname, but fullname missing)
CREATE TYPE my_ks.address (street text, person fullname); // fails: Cannot resolve UDTs
// after
CREATE TYPE my_ks.fullname (first text, last text);
CREATE TYPE my_ks.address (street text, person frozen<fullname>);

Defensive patterns

Strategy: validation

Validate before calling

Set<String> defined = allUdtNames(); for (UserType t : udts) for (String dep : dependenciesOf(t)) if (!defined.contains(dep)) throw new IllegalStateException("Missing UDT dependency: " + dep);

Try / catch

try { Types t = Types.rawBuilder(ksName).add(definitions).build(); } catch (ConfigurationException e) { /* trigger schema repair / restore full type set */ }

Prevention

Migrate UDTs together with their dependent types
Never hand-edit system_schema.types
Verify schema snapshots contain all UDT definitions before restore
Create leaf types before dependents in bootstrap scripts

When it happens

Trigger: Calling Types.build / fetchTypes / deserialize for a keyspace whose stored UDT definitions contain references to missing types or are cyclic, so vertex.prepare cannot resolve every definition and types.types.size() != definitions.size().

Common situations: Corrupted or partially-written schema tables after a failed migration; manually editing system_schema.types; restoring a schema snapshot with a subset of UDTs; cross-keyspace copy where dependent types were not migrated together.

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

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