Expertise AI Knowledge Base

   Playbooks  Troubleshooting Guide

Troubleshooting Guide

Common issues, error messages, and how to fix them

Last updated on October 27, 2025

Troubleshooting Guide

Common Issues and Solutions

Issue: Missing @stop_playbook

Symptom: Validation error "No valid path to stop_playbook"
Cause: One or more branches don't reach @stop_playbook
Solution: Ensure every branch in your playbook eventually reaches @stop_playbook. Trace each option through to verify.
Example fix:
Before (broken):
3. @ask_question: "Interested?" @show_options["Yes", "No"]
    - If "Yes", proceed to Step 4.
    # No path for "No" answer!

4. @ask_question: "Email?"

5. @stop_playbook
After (fixed):
3. @ask_question: "Interested?" @show_options["Yes", "No"]
    - If "Yes", proceed to Step 4.
    - If "No", proceed to Step 6.

4. @ask_question: "Email?"

5. @stop_playbook

6. @mention_specifically: "No problem!" @stop_playbook

Issue: Invalid Step References

Symptom: "Step X referenced but does not exist"
Cause: Branching bullets reference step numbers that don't exist
Solution: Check all branching bullets reference valid step numbers. Add missing steps or update references.

Issue: Tool Combination Error

Symptom: "@initialize_live_chat must be in its own step"
Cause: @initialize_live_chat is combined with other tools
Solution: Move @initialize_live_chat to its own dedicated step with no other tools.
Example fix:
Before (broken):
5. @mention_specifically: "Connecting you now..." @initialize_live_chat
After (fixed):
5. @mention_specifically: "Connecting you now..."

6. @initialize_live_chat
    - Proceed to Step 7.

7. @stop_playbook

Issue: Validation Failures (Structure)

Symptom: "Playbook has structural issues"
Cause: Multiple structural problems with formatting, numbering, or flow
Solution: Use "Rewrite with AI" button to automatically fix formatting and structure problems.
Steps:
  1. Click "Rewrite with AI" in the editor
  1. Wait for AI to analyze and fix the playbook (10-30 seconds)
  1. Review the proposed changes
  1. Click "Apply" to accept or manually adjust
  1. Save to validate the corrected version

Issue: Tool Not Working

Symptom: Tool doesn't execute or shows error during testing
Solution: Verify tool configuration and requirements.

For @create_hubspot_ticket

Check:
  • ✓ HubSpot connected?
  • ✓ Pipeline and stage configured in tool settings?
  • ✓ Name, email, and problem collected before tool call?
  • ✓ HubSpot permissions allow ticket creation?

For @initialize_live_chat

Check:
  • ✓ HubSpot connected with live chat enabled?
  • ✓ Tool in its own step?
  • ✓ Active hours configured?
  • ✓ Email collected first?
  • ✓ Test during configured active hours?

For @share_booking_link

Check:
  • ✓ Calendar integration connected?
  • ✓ Meeting types configured?
  • ✓ Available time slots in calendar?

Issue: Playbook Not Triggering

Symptom: Trigger phrase doesn't activate the playbook
Possible causes:
  1. Playbook is inactive - Toggle playbook to "Active"
  1. Trigger phrase doesn't match - Type trigger phrase exactly as configured
  1. Another playbook already active - Check if another playbook has same/similar trigger
  1. Chatbot not deployed - Ensure chatbot is deployed and active

Getting Help

In-App Resources

Hover tooltips: Hover over tools to see what each tool does
Tool panel: Shows which tools are used in your playbook (highlighted)
Validation messages: Explain what's wrong and where

Contact Support

When to contact:
  • Persistent errors after troubleshooting
  • Integration issues
  • Data not syncing to CRM
  • Technical errors or bugs
What to provide:
  • Playbook ID or name
  • Steps to reproduce
  • Screenshots of errors
  • What you've already tried

Related Pages