name: diagnose description: Use when a test fails and you need to diagnose the root cause. Run the test, read errors, trace through generated and source code, fix, and verify. allowed-tools: Bash(./mvnw:), Bash(javap:), Bash(unzip:), Bash(grep:)

Diagnose Test Failure

Overview

Systematic diagnosis of test failures in the Morphia project. Run the test, read the full error, trace the root cause through source and generated code, fix minimally, and verify.

Workflow

1. Run the failing test

   ./mvnw test -pl :module-name -Dtest="ClassName#methodName" -Ddeploy.skip=true
   

   • Use -Ddeploy.skip=true to skip dokka
   • Do NOT use -am with -Dtest= (applies test filter to all modules)
   • If dependencies need rebuilding first:

     ./mvnw install -pl :dep1,:dep2 -DskipTests -Ddeploy.skip=true -Dinvoker.skip=true
     

2. Read the full error - stack trace, error message, line numbers. Don't skip anything.

3. Find relevant code - Read both source AND generated code:

   • Source: src/main/, src/test/
   • Generated bytecode: target/test-classes/ - use javap -c -p ClassName to decompile
   • Generated sources: target/generated-sources/
   • Interfaces from dependencies: check ~/.m2/repository/ source jars with unzip -p

4. Trace the root cause - Follow the error backward:

   • What method is missing/wrong?
   • What generated it? All critter bytecode comes from the Class-File API generators in core/src/main/java/dev/morphia/critter/parser/generator/ (see "Critter Code Generation" below).
   • Was it the AOT path (critter-maven, woven __read*/__write* methods) or the runtime path (hidden nestmate accessors)?
   • What does the interface/superclass require?
   • Compare with a working generator for the same pattern (e.g. how PropertyAccessorGenerator boxes primitives)

5. Fix minimally - One change at a time. Rebuild affected modules:

   ./mvnw install -pl :morphia-core,:critter-maven -DskipTests -Ddeploy.skip=true -Dinvoker.skip=true
   

6. Verify - Re-run the failing test AND related tests in the same class.

Critter Code Generation

Critter generates bytecode with the Class-File API (java.lang.classfile), using the jdk-classfile-backport library (package io.smallrye.classfile) so it runs on Java 17. There is no Gizmo or ASM in the generators. Everything is in core/src/main/java/dev/morphia/critter/parser/generator/, and CritterGenerator is the entry point.

| Generator | Produces | |-----------|----------| | AddFieldAccessorMethods / AddMethodAccessorMethods | AOT only: rewrites the entity class to add synthetic __readXxx/__writeXxx methods | | PropertyAccessorGenerator | AOT only: a PropertyAccessor that calls the woven __read*/__write* methods | | NestmateAccessorGenerator | Runtime only: a PropertyAccessor using direct getfield/putfield/invokevirtual, defined as a hidden nestmate (Lookup.defineHiddenClass(..., NESTMATE)) and registered in NestmateAccessorRegistry | | PropertyModelGenerator | A CritterPropertyModel per property | | EntityModelGenerator | The CritterEntityModel for the entity | | VarHandleAccessorGenerator | A VarHandle/MethodHandle-based accessor; not used by the main pipeline right now (only TestVarHandleAccessor) |

The two paths:

• AOT: critter-maven (generate-models / generate-test-models) calls CritterGenerator.generate(type, loader, false). It writes the generated models and the woven entity classes to disk under __morphia/<entity>/.
• Runtime: when no pre-generated model is on the classpath, CritterMapper calls generate(type, loader, true). That defines classes in a CritterClassLoader plus hidden nestmates. If it fails, it logs once and falls back to a reflective EntityModel. Hidden nestmates need full privilege access, so an entity outside Morphia's module (on the classpath: loaded by a different class loader) fails with a NestmateAccessException; CritterMapper logs a specific "can't access ... isn't in Morphia's module" warning for it. That's expected for those layouts, and the fix is critter-maven AOT models, not a generator change.

PropertyFinder rejects some entities for AOT with UnsupportedOperationException("AOT skip: ..."): inherited fields the entity can't reach and whose declaring class can't be rewritten (e.g. a private field in a library superclass), fields shadowing a superclass field, array-typed fields, and entities whose @Id is on a getter. Entities with no @Id at all (e.g., embedded types) are generated normally. A final field's __writeXxx sets it through a cached java.lang.reflect.Field, since putfield may only write a final field from a constructor. An inherited field from a superclass in the same output directory or jar gets its __readXxx/__writeXxx methods woven into that superclass, which the entity inherits. The rejected entities use runtime generation instead, so an "AOT skip" warning in the critter-maven output is expected for them and is not an error.

Common Morphia/Critter Issues

| Error | Likely Cause | |-------|-------------| | AbstractMethodError | A generated class is missing an interface method. Generators emit methods with explicit erased descriptors (e.g. get(Ljava/lang/Object;)Ljava/lang/Object;), and nothing adds bridge methods for you | | VerifyError / Bad type on operand stack | Usually a primitive/reference mismatch: a primitive was used where an Object was expected, or the reverse, without boxing or unboxing | | ClassCastException in a generated accessor | checkcast to the wrong owner (for an inherited field, the declaring class vs the entity class) or to the wrong wrapper type | | IllegalAccessError from a nestmate accessor | The hidden class was defined against the wrong lookup class. It must be privateLookupIn the field's declaring class | | NoSuchMethodError __read*/__write* | The AOT accessor ran against an unwoven entity class, e.g. the woven class from generated-classes/critter is not ahead of the original on the classpath | | ClassNotFoundException __morphia.* | Critter code generation didn't run or class not registered |

Key Gotchas

• The Class-File API is low-level: no automatic boxing, casting, or bridge methods. Emit each step explicitly.
• Boxing: invokestatic Wrapper.valueOf(prim)Wrapper. Unboxing: checkcast Wrapper, then invokevirtual Wrapper.xxxValue(). Helpers live in GenerationUtils (PRIMITIVE_TO_WRAPPER, primitiveUnboxMethod, primitiveClassDesc).
• checkcast only accepts reference types. To get a primitive from an Object, cast to the wrapper and then unbox.
• Keep non-public types out of generated descriptors. AOT accessors use Object in __read*/__write* signatures for reference types, and the cast happens inside the entity.
• Inspect generated classes with javap -c -p. AOT output is under target/generated-classes/critter (main) or target/test-classes/**/__morphia/ (tests). Runtime-generated classes are in memory only.