Find the cause. Keep the evidence.
Diagnose the right process, watched output, pending restart and framework follow-up without guessing.
“I saved, but nothing changed”
- Check the target JVM. Confirm that this application started with the intended agent and version. An IDE or MCP connection can target a different process.
- Check the compiler output. The default route watches compiled files, not editor text. Use the build that writes the configured output directories.
- Wait for startup. The default watcher delay is 30 seconds.
- Check admission. A paused agent, failed build hold or deferred request boundary can retain a valid edit.
- Inspect the class result. Ask DIAGNOSE for the exact class and inspect PENDING for incomplete changes.
- Check your edit’s scope. Reflection, hierarchy, schema and framework changes can have different results.
Use the tool that answers your question
| Question | Tool / command | What it establishes |
|---|---|---|
| Which JVM and capabilities? | DOCTOR | Bounded session/runtime/watcher evidence, not completion. |
| What happened to this class? | DIAGNOSE <class> | Last outcome, byte source and restart implications. |
| What still needs restart? | PENDING | Restart ledger plus admission pause/pending counts. |
| Is work waiting? | HEALTH | Reload/failure/latency and work-in-progress status. |
| Were these exact bytes applied? | VERIFY | Correlated class/hash receipt; still check application behavior. |
| What happened across the session? | sessionLog | Timestamped status history. |
Command names here describe the protocol; they are not all bare shell commands. Use the IDE/build/MCP integration or follow the full socket syntax in the reference. Newer commands need matching agent/client builds.
Common symptoms and next steps
New method works in Java but reflection cannot find it
On a stock JVM the original Class does not gain companion members. Compile supported watched callers, use a documented framework adapter, or restart/use a compatible enhanced runtime when original-class visibility is required.
Understand reflective visibility →Properties changed on disk but runtime values stayed old
Inspect rejection/uncheckable output, source ownership, higher-priority values and admission holds. Fix the invalid candidate and save again. Do not assume a startup-only consumer recreates itself.
Inspect the configuration path →A listener stopped and the replacement did not start
Check retirement timeout and registration/expression errors. A failed addition can leave no new consumer, with old ownership retained or retired depending on the stage. Correct the input and follow the direct-path retry diagnostic. Do not infer successful delivery from class reload.
Inspect consumer lifecycle limits →A generated model has a field, but persistence cannot use it
Check type-system/schema preparation, native reflective visibility and the mapping path separately. Code generation alone does not install a database column.
Inspect the persistence layers →Reload waits while requests keep running
Request mode reopens traffic after its drain deadline and queues the edit for a natural idle boundary. Check unfinished async work and Callable workers, especially when cancellation is ignored.
Inspect request-boundary behavior →Recover deliberately
For a bad implementation, restore the previous source and compile again. Recheck the same application behavior. If a lifecycle/registration/schema step failed, use the diagnostic’s specific recovery or restart requirement; source reversal does not undo its side effects.
For an instrumentation issue, the source supports excludeClasses for a named class or structuralReload=false for method-body-only operation. These are startup configuration changes. Removing the agent flag runs without the agent after restart.
Report a reproducible issue
Include the agent/integration versions, Java vendor/version, OS, framework versions, launch route, watched output, minimal before/after edit, compile command, expected/observed result and relevant DIAGNOSE/PENDING output. State whether the same edit works after a fresh restart.
Use synthetic names and remove credentials, customer identities, private paths and application data from logs or fixtures. The protocol can expose class names and local output paths. For vulnerability reports follow the project’s security policy.
Sources & version scope
Documentation source 1.4.0 · evidence baseline 75535bd · reviewed 19 October 2026. Check your installed artifact; source features may postdate a release.