Definition #
Agent Troubleshooting is a structured method for identifying, isolating, and resolving runtime issues in candidate journeys.
Why it matters #
Fast diagnosis reduces candidate drop-off, protects conversion quality, and shortens recovery time during live operations.
How it works #
Use a layered approach:
- Reproduce with exact candidate path and step sequence.
- Inspect data state (candidate fields, metadata, workflow variables).
- Check rendering layer (runner content and merged output).
- Validate integration responses (API/webhook/service outcomes).
- Confirm persistence (database record creation/update timing).
- Apply fix + verify with the same scenario.
Configuration fields #
When investigating, always capture:
- Candidate id / token
- Agent id / path id / step id
- Widget type and configuration snapshot
- Relevant merge fields and raw source values
- Integration request/response payload (masked if sensitive)
- Error code and event timestamp window
Example scenario #
Stale value after option selection #
Symptom: Next step shows old or empty value in confirmation text.
Likely cause: frontend state not refreshed after backend write.
Check: whether step progression returns refresh indicator and re-fetches workflow data.
Merge field appears empty #
Symptom: rendered text shows blank where dynamic field is expected.
Likely cause: wrong key, missing metadata value, or merge processing not applied to that property.
Check: raw candidate data + metadata + template token naming + property merge handling.
Signature flow returns 409 (processing) #
Symptom: signing URL creation fails with “cannot create ceremony, envelope processing.”
Likely cause: race condition between envelope readiness and ceremony request.
Check: retry/backoff behavior, persistence timing for sign-document mapping, webhook order tolerance.
Common mistakes #
- Testing with inconsistent candidate data between runs
- Debugging UI only, without checking backend persistence timing
- Assuming webhook event order is deterministic
- Not separating unrelated external errors from primary root cause
- Fixing symptom text without validating data lifecycle
Troubleshooting checklist #
- Reproduce with one deterministic test candidate
- Confirm source data written successfully before render step
- Verify merge token names exactly match available context keys
- Validate front-end refresh behavior after save/proceed actions
- Inspect integration status codes and retry behavior
- Check webhook timing gaps and lookup fallbacks
- Re-test end-to-end after fix (including back/forward navigation)