diagnose
- Repo stars 1,680
- License Apache-2.0
- Author repo morphia
- Domain
- Engineering
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 94 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @MorphiaOrg · Apache-2.0
- Token usage
- Lean
- Setup complexity
- Plug-and-play
- External API key
- Not required
- Operating systems
- macOS
- Runtime requirements
- No explicit requirements detected
- Detected file/system behavior
-
- Read-only
- Write / modify
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# 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? (Gizmo generator? ASM generator?)
- What does the interface/superclass require?
- Compare with working examples (ASM-based generators have bridge methods; check if Gizmo-based ones do too)
5. **Fix minimally** - One change at a time. Rebuild affected modules:
```
./mvnw install -pl :critter-core,:critter-maven -DskipTests -Ddeploy.skip=true -Dinvoker.skip=true
```
6. **Verify** - Re-run the failing test AND related tests in the same class.
## Common Morphia/Critter Issues
| Error | Likely Cause |
|-------|-------------|
| `AbstractMethodError` | Missing bridge methods in generated bytecode (generic interface erasure) |
| `Cannot checkcast to primitive` | Gizmo `checkCast` doesn't work on primitives - use `smartCast` |
| `Cannot convert primitive to Object` | Need boxing: `smartCast(result, wrapperType)` |
| `NoSuchMethodError __read*/__write*` | Accessor methods not generated on entity class |
| `ClassNotFoundException __morphia.*` | Critter code generation didn't run or class not registered |
## Key Gotchas
- Gizmo does NOT auto-generate bridge methods for generic interfaces
- Primitive types need explicit boxing/unboxing via `smartCast`
- `checkCast(Object -> wrapper)` then `smartCast(wrapper -> primitive)` for unboxing
- `smartCast(primitive -> wrapper)` for boxing
- Always check both Gizmo (`parser/gizmo/`) and ASM (`parser/asm/`) generators for patterns Sections and files
Listed in source order.
sections -> Overview → Workflow → Common Morphia/Critter Issues → Key Gotchas
terms -> Run the failing test · Read the full error · Find relevant code · Trace the root cause · Fix minimally · Verify
files/cmd -> -Ddeploy.skip=true · -am · -Dtest= · src/main/ · src/test/ · target/test-classes/ · javap -c -p ClassName · target/generated-sources/
body sha256 -> 7fbb6c65ec81
Workflow
Run the failing test Use
-Ddeploy.skip=trueto skip dokka Do NOT use-amwith-Dtest=(applies test filter to all modules) If dependencies need rebuilding first: Read the full error - stack trace, error message, line numbers. Don't skip anything.Common Morphia/Critter Issues
Error · Likely Cause
AbstractMethodError· Missing bridge methods in generated bytecode (generic interface erasure)Cannot checkcast to primitive· GizmocheckCastdoesn't work on primitives - usesmartCastCannot convert primitive to Object· Need boxing:smartCast(result, wrapperType)NoSuchMethodError __read*/__write*· Accessor methods not generated on entity classKey Gotchas
Gizmo does NOT auto-generate bridge methods for generic interfaces Primitive types need explicit boxing/unboxing via
smartCastcheckCast(Object -> wrapper)thensmartCast(wrapper -> primitive)for unboxingsmartCast(primitive -> wrapper)for boxing Always check both Gizmo (parser/gizmo/) and ASM (parser/asm/) generators for patterns