Overview #
Agent Troubleshooting helps you identify and fix problems that happen during a Candidate's Journey. This includes issues with data not appearing correctly, Steps behaving unexpectedly, or integrations failing.
How to Approach Troubleshooting #
Follow a structured process:
- Reproduce the issue — Go through the same Journey with a test Candidate using the same inputs.
- Check the data — Open the Candidate record and review what was collected at each Step.
- Check what is displayed — Look at what the Candidate sees in the Runner and compare it to what you expect.
- Check integrations — If the issue involves email, SMS, or webhooks, check the delivery status and logs.
- Fix and verify — Make the change, then retest with a new test Candidate.
Common Issues and How to Fix Them #
Missing or Blank Data in Messages #
What happens: A message or confirmation shows blank where data should appear (e.g., "Hello, " instead of "Hello, John").
Possible causes:
- The Merge Field name does not match the field name in the system
- The data was not collected before this Step
- The field name has a typo or extra space
How to fix:
- Check the Merge Field name (e.g., {{ firstname }}).
- Verify that the data is collected in an earlier Step.
- Open the test Candidate's record and check if the field has a value.
- Correct the Merge Field name if needed.
Old Data Showing After an Update #
What happens: The Candidate selects a new option or updates a field, but the next Step still shows the old value.
Possible causes:
- The page did not refresh after the update
- The data was saved to one field but the next Step reads from a different field
How to fix:
- Check that the field being saved matches the field being read.
- Test again with a fresh Candidate to see if the issue persists.
- If the issue is a display refresh problem, report it to support.
Document Signing Fails #
What happens: The Candidate cannot sign a document — the system shows an error message about the document not being ready.
Possible causes:
- The document is still being prepared when the Candidate tries to sign
- The document template has an issue
How to fix:
- Check Webhook Logs for any errors related to the signing service.
- Retry the test — the issue may be temporary.
- If the issue persists, check the document template configuration.
- Contact support if the error continues.
Email or SMS Not Sent #
What happens: The Candidate does not receive the expected email or SMS.
Possible causes:
- The Candidate's email or phone number is missing or incorrect
- The email/SMS Step is not configured correctly
- The email was blocked by a spam filter
How to fix:
- Check the Candidate record — is the email/phone field populated?
- Check the Webhook Logs or email delivery status.
- Verify the email/SMS Step configuration in the Agent Editor.
General Troubleshooting Checklist #
- ✅ Reproduced the issue with a test Candidate
- ✅ Checked the Candidate record for correct data
- ✅ Verified that Merge Field names match the field names in the system
- ✅ Confirmed that the display refreshes correctly after updates
- ✅ Checked integration logs (email, SMS, webhook) for errors
- ✅ Retested after making changes
Common Mistakes #
- Testing with the same Candidate repeatedly (use a fresh test Candidate each time)
- Only checking what the Candidate sees, without checking the backend data
- Assuming all integrations run in a fixed order (they may not)
- Fixing the visible symptom without checking the underlying data
- Not testing the full Journey end to end after making a fix
When to Contact Support #
If you have followed the steps above and cannot resolve the issue:
- Collect the Candidate details (name, ID, Agent name).
- Note the exact Step where the issue occurs.
- Take screenshots of the error or unexpected behaviour.
- Email support@zirpa.ai with all the details.
See How to Get More Help for more information.