# Diagnose

> 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.

- Skill: `morphiaorg/diagnose` (Agent Skill)
- Install (CLI): `npx skillmds@latest add morphiaorg/diagnose`
- Raw SKILL.md: https://api.skillmd.com/api/skills/morphiaorg/diagnose/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: morphiaorg (https://skillmd.com/u/morphiaorg)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/morphiaorg/diagnose

---


# 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