KB-007: Decision Trees and Troubleshooting Guide
Target Audience: Implementation team, support team, troubleshooting specialists
Learning Objectives:
- Systematically diagnose and resolve common issues
- Use decision trees for efficient problem-solving
- Apply troubleshooting best practices
- Know when to escalate issues
Estimated Reading Time: 45 minutes
Table of Contents
- Troubleshooting Philosophy (5 min)
- Decision Tree: System Not Working (10 min)
- Common Issues and Solutions (25 min)
- Escalation Guide (5 min)
- Preventive Maintenance (5 min)
1. Troubleshooting Philosophy
1.1 The Symphony Core Approach
Core Principles:
- Systematic, Not Random: Follow decision trees, don't guess
- Document Everything: Record symptoms, tests, and solutions
- Test One Thing at a Time: Isolate variables
- Start Simple: Check obvious things first (is it plugged in?)
- Learn from Every Issue: Update documentation with solutions
1.2 Before You Start Troubleshooting
Gather Information:
- ❓ What's the symptom? (Specific, observable problem)
- ❓ When did it start? (Timing can reveal causes)
- ❓ What changed recently? (New snapshot, config change, etc.)
- ❓ Who is affected? (One client? All clients? One industry?)
- ❓ Can you reproduce it? (Consistent vs intermittent)
Have Ready:
- ✅ Access to affected sub-account
- ✅ Access to base snapshots (for comparison)
- ✅ List of recent changes
- ✅ Client's ExtendlyOS form data (if applicable)
- ✅ Workflow activity logs
1.3 The 5-Minute Rule
Before diving deep:
- 60 seconds: Check the obvious (is workflow published? is domain connected?)
- 2 minutes: Review recent changes in sub-account
- 2 minutes: Test with a fresh contact (eliminate re-entry issues)
If not resolved in 5 minutes: Follow the decision trees below
2. Decision Tree: System Not Working
2.1 Master Troubleshooting Decision Tree
2.2 Decision Tree: Workflow Not Triggering
Quick Checks:
- ✅ Workflow published (not in draft)?
- ✅ Trigger conditions met (right tags, right source)?
- ✅ Contact hasn't gone through before (GHL re-entry block)?
- ✅ Required custom values populated?
- ✅ Workflow has no errors in logs?
Deep Dive: See KB-005:5.1 for detailed workflow troubleshooting
2.3 Decision Tree: Communications Not Sending
Email Quick Checks:
- ✅ Dedicated domain configured (Settings → Email Services)?
- ✅ DNS records set (SPF, DKIM, DMARC)?
- ✅ Domain warmed up (gradual volume increase)?
- ✅ Email content professional (no spam triggers)?
- ✅ Test email to yourself successful?
SMS Quick Checks:
- ✅ Phone number purchased and active?
- ✅ Contact phone has country code (+1)?
- ✅ SMS content professional (no spam words)?
- ✅ SMS sending limit not reached?
- ✅ Test SMS to your phone successful?
Deep Dive: See KB-005:5.1 for detailed communication troubleshooting
2.4 Decision Tree: Calendar Not Showing Availability
Quick Checks:
- ✅ Calendar connected and authorized?
- ✅ Availability hours set correctly?
- ✅ Timezone matches client location?
- ✅ No conflicting appointments blocking all slots?
- ✅ User assigned to calendar?
- ✅ Buffer times reasonable (15-30 min)?
Setup Guide: See KB-004:Task 7-8 for calendar configuration
2.5 Decision Tree: Custom Values Showing Placeholders
Common Syntax Errors:
❌ WRONG: `{{ custom_values.businessname }}`
✅ CORRECT: `{{custom_values.business_name}}`
❌ WRONG: `{{ custom_values.business_name }}` (spaces)
✅ CORRECT: `{{custom_values.business_name}}`
❌ WRONG: `{{custom_values.businessName}}` (wrong case)
✅ CORRECT: `{{custom_values.business_name}}`
Quick Checks:
- ✅ Custom value has a value (not blank)?
- ✅ Syntax is
{{custom_values.field_name}}(no spaces)? - ✅ Field name spelled exactly right (check Settings)?
- ✅ Template/page republished after value update?
- ✅ Custom value wasn't deleted or renamed?
Deep Dive: See KB-003:4.5 for comprehensive custom values troubleshooting
2.6 Decision Tree: Pages Not Loading
Quick Checks:
- ✅ Domain added in Settings → Domains?
- ✅ DNS A record and CNAME configured?
- ✅ SSL certificate shows "Active" (wait 24-48 hrs)?
- ✅ Funnel/page published (not draft)?
- ✅ Using correct URL (subdomain.domain.com/page)?
Setup Guide: See KB-004:Task 3 for domain configuration
2.7 General Diagnostic Procedure
When issue doesn't fit above categories:
STEP 1: Isolate the Scope
├─ One client affected? → Client-specific configuration issue
├─ One industry affected? → Industry base snapshot issue
├─ All clients affected? → Universal base or system-wide issue
└─ Random clients affected? → Environmental/timing issue
STEP 2: Identify Recent Changes
├─ New snapshot loaded? → Compare with previous version
├─ Workflow modified? → Review workflow history
├─ Settings changed? → Check activity log
└─ Nothing changed? → External factor (GHL platform, integrations)
STEP 3: Reproduce Consistently
├─ Can you make it happen every time? → Systematic issue
├─ Intermittent? → Timing, rate limits, or race condition
└─ Only with certain contacts? → Contact data issue
STEP 4: Compare Working vs Broken
├─ Find a working sub-account (same industry)
├─ Compare workflows, settings, configurations
├─ Identify the difference
└─ Apply fix to broken account
STEP 5: Test Fix
├─ Apply fix in test environment first
├─ Verify fix works
├─ Apply to production
└─ Monitor for recurrence
3. Common Issues and Solutions
3.1 Workflow Issues
Issue 1: Workflow Not Triggering
Symptoms:
- Lead submitted, no automation fires
- Appointment booked, no confirmation sent
- Form filled, no follow-up occurs
Root Causes:
- Workflow in draft mode
- Trigger conditions not met
- Contact already in workflow
- Workflow has errors
- Required custom values missing
Solutions:
Check 1: Workflow Status
Location: Automations → Select workflow → Check status badge
If "Draft" → Click Publish
Check 2: Trigger Conditions
Review workflow trigger:
- Tags required? → Verify contact has tags
- Source match? → Check contact source
- Form specific? → Verify correct form submitted
Check 3: Contact Re-entry
GHL prevents contacts from re-entering same workflow
Option A: Use fresh test contact (new email/phone)
Option B: Clone workflow (creates new workflow ID)
Option C: Check contact → Workflow History to confirm
Check 4: Workflow Logs
Location: Automations → Workflow → Activity Log
Look for:
- Error messages (red)
- Failed steps
- Missing data warnings
Check 5: Custom Values
If workflow uses custom values:
Settings → Custom Values → Verify populated
OR use ExtendlyOS form to fill all at once
Prevention:
- Always test workflows with fresh contacts
- Document trigger conditions clearly
- Set up workflow error notifications
- Use workflow testing mode before going live
Issue 2: Workflow Running Multiple Times
Symptoms:
- Contact receives duplicate emails/SMS
- Actions execute repeatedly
- Loop detected in logs
Root Causes:
- Multiple triggers firing simultaneously
- Workflow triggering itself (loop)
- Re-entry prevention not working
- Contact updated multiple times
Solutions:
Check for Duplicate Triggers:
Review workflow triggers:
- Multiple forms triggering same workflow?
- Multiple tags applied simultaneously?
- Contact updated by multiple sources?
Fix: Consolidate triggers or add "Wait for" conditions
Check for Workflow Loops:
Workflow loop example:
1. Workflow updates contact
2. Contact update triggers same workflow
3. Loop continues infinitely
Fix: Add exit conditions or use different trigger
Add Re-entry Prevention:
Add filter at start of workflow:
"Has not been through this workflow in last X days"
Settings: Add → Filter → Workflow History
Issue 3: Delays Not Working Correctly
Symptoms:
- Messages send immediately instead of waiting
- Wait steps skipped
- Timing incorrect
Root Causes:
- Wait step configured incorrectly
- Timezone issues
- Business hours logic broken
- Workflow queue delays
Solutions:
Verify Wait Configuration:
Wait Step Options:
- Wait for X minutes/hours/days (absolute time)
- Wait until specific time (e.g., 9 AM next day)
- Wait for contact to do something (trigger)
Check: Is correct option selected?
Check Timezone:
Settings → Account Settings → Timezone
vs.
Workflow wait step timezone
Must match for correct timing
Business Hours Logic:
If using "during business hours" condition:
- Settings → Business Hours configured?
- Days and hours set correctly?
- Timezone matches business location?
3.2 Communication Issues
Issue 4: Emails Going to Spam
Symptoms:
- Client reports not receiving emails
- High bounce rate
- Gmail/Outlook flagging as spam
Root Causes:
- No dedicated domain
- DNS records missing/incorrect
- Domain not warmed up
- High sending volume
- Email content triggers spam filters
Solutions:
Step 1: Configure Dedicated Domain
Settings → Email Services → Dedicated Domain
- Add domain (e.g., mail.clientdomain.com)
- Wait for verification
- Status must show "Verified"
See KB-004:Task 4 for detailed setup
Step 2: Verify DNS Records
Required DNS records:
- SPF record (TXT)
- DKIM record (TXT)
- DMARC record (TXT)
Tools to check:
- MXToolbox.com
- Google Admin Toolbox
Common error: Records not added at domain registrar
Step 3: Warm Up Domain
New domains need gradual volume increase:
Week 1: 10-20 emails/day
Week 2: 50-100 emails/day
Week 3: 200-500 emails/day
Week 4: 1000+ emails/day
Sudden high volume → spam filters triggered
Step 4: Check Email Content
Spam Triggers:
❌ ALL CAPS SUBJECT LINES
❌ Excessive !!!! or $$$
❌ Words like "Free", "Win", "Guarantee"
❌ No unsubscribe link
❌ Suspicious links
Tools: Mail-Tester.com (spam score test)
Step 5: Monitor Metrics
Marketing → Email Analytics
Watch for:
- Bounce rate > 5% (too high)
- Spam complaints > 0.1% (concerning)
- Open rate < 15% (deliverability issue)
Action: Pause sending, fix issues, warm up again
Issue 5: SMS Not Sending
Symptoms:
- SMS automation not delivering
- No error but recipient doesn't receive
- Workflows show "SMS sent" but nothing delivered
Root Causes:
- Phone number not configured
- Contact phone missing country code
- SMS content flagged as spam
- Account SMS limit reached
- Recipient phone invalid
Solutions:
Step 1: Verify Phone Number
Settings → Phone Numbers
- Must have active phone number
- Status: "Active"
- Type: "SMS Capable"
If missing: Purchase phone number (KB-004:Task 6)
Step 2: Check Contact Phone Format
Required format: +1XXXXXXXXXX
❌ WRONG: 5551234567
❌ WRONG: (555) 123-4567
❌ WRONG: 555-123-4567
✅ CORRECT: +15551234567
Fix: Add country code (+1 for US/Canada)
Step 3: Review SMS Content
Carrier Spam Filters:
❌ "Free", "Win", "Click here"
❌ Excessive links (more than 1-2)
❌ ALL CAPS
❌ Too many emojis
✅ Professional tone
✅ Business name clear
✅ One clear CTA
✅ Opt-out option
Step 4: Check Account Limits
Settings → Account → Usage
- SMS sent this month vs. limit
- If limit reached → Contact GHL support
Upgrade options available for higher volume
Step 5: Test with Your Phone
Create test contact with YOUR phone number
Trigger SMS automation
Did you receive it?
YES → Issue is with recipient's phone
NO → System-wide issue, escalate
3.3 Calendar Issues
Issue 6: No-Shows Not Being Tracked
Symptoms:
- Appointments marked as no-show but no automation fires
- No-show recovery workflow not triggering
Root Causes:
- Appointment status not updated
- No-show workflow not connected
- Trigger conditions wrong
Solutions:
Manual No-Show Marking:
Calendars → Appointments → Select appointment
→ Mark as "No Show"
Must manually mark (GHL doesn't auto-detect)
Configure No-Show Workflow:
Trigger: Appointment Status Changed to "No Show"
Actions:
1. Wait 1 hour
2. Send "We missed you" SMS/Email
3. Send rescheduling link
4. Tag contact: "No-Show"
3.4 Custom Values Issues
Issue 7: Custom Values Not Updating After Form Submission
Symptoms:
- ExtendlyOS form submitted
- Custom values still blank
- Or values show old data
Root Causes:
- Form not connected to custom values correctly
- Form field mapping wrong
- Workflow populating values has error
Solutions:
Check Form Field Mapping:
Forms → ExtendlyOS form → Fields
Each field should map to:
Custom Field → Custom Values → [specific value name]
If not mapped → Values won't populate
Check Workflow:
ExtendlyOS form usually triggers workflow
that populates custom values
Workflow: Look for "Update Contact Custom Field" actions
Verify: Each action maps form field → custom value
Manual Population:
If form not working:
Settings → Custom Values → Manually fill each value
OR
Use contact custom fields as backup
3.5 Integration Issues
Issue 8: GMB Review Link Not Working
Symptoms:
- Review link shows error
- Link doesn't open review form
- Reviews not being captured
Root Causes:
- GMB not integrated
- Wrong review link format
- GMB authorization expired
Solutions:
Step 1: Verify GMB Integration
Settings → Integrations → Google
Status must show: "Connected"
If not → Click "Connect Google" and authorize
Step 2: Get Correct Review Link
Two methods:
Method 1: GMB Dashboard
- Go to Google My Business
- Select location
- Get reviews → Share review form
- Copy short URL
Method 2: Place ID
Format: https://search.google.com/local/writereview?placeid=YOUR_PLACE_ID
Step 3: Test Review Link
Open link in incognito browser
Should show: Google review form
If error → Link is wrong, get new link
Step 4: Update Custom Value
Settings → Custom Values
Find: gmb_review_link or google_review_link
Paste: Correct review URL
See KB-003:3.7 for details
Issue 9: Calendar Sync Delays
Symptoms:
- Bookings appear in GHL but not Google Calendar
- Or vice versa
- Delay of hours
Root Causes:
- Calendar sync interval
- Authorization expired
- Calendar connection issue
Solutions:
Check Sync Interval:
GHL syncs every 5-15 minutes (not instant)
Wait 15 minutes and refresh
If still not syncing → Continue troubleshooting
Reconnect Calendar:
Settings → Calendar → Connections
Find: Google Calendar
Action: Disconnect → Reconnect
Reauthorize access
Force Sync:
Some calendar connections have "Sync Now" button
Settings → Calendar → Connections → Sync Now
If no button → Wait for automatic sync
3.6 Data Issues
Issue 10: Duplicate Contacts
Symptoms:
- Same person multiple times
- Split conversation history
- Missed follow-up
Root Causes:
- Duplicate detection disabled
- Different email formats
- Different phone formats
- Import without deduplication
Solutions:
Enable Duplicate Detection:
Settings → Contact Settings → Duplicate Detection
Options:
- Match by email only
- Match by phone only
- Match by email OR phone (most common)
- Match by email AND phone
Recommended: Email OR Phone
Merge Duplicates:
Method 1: Manual Merge
Contacts → Search → Select duplicates → Merge
Method 2: Find Duplicates Tool
Tools → Find Duplicates → Review → Merge
Prevent on Import:
When importing contacts:
✅ Check "Update if exists" option
✅ Use email as matching field
✅ Preview before import
This prevents new duplicates during import
Standardize Formats:
Before import:
- Emails: all lowercase
- Phones: +1-XXX-XXX-XXXX format
- Remove special characters
4. Escalation Guide
4.1 When to Escalate
Escalate Immediately if:
- ⚠️ System-wide outage (all clients affected)
- ⚠️ Data loss or corruption
- ⚠️ Security breach suspected
- ⚠️ Billing/payment processing failure
- ⚠️ Critical workflow completely broken
Escalate After Troubleshooting if:
- ⏱️ Spent 30+ minutes without resolution
- ⏱️ Issue affects multiple clients
- ⏱️ Root cause unclear after following decision trees
- ⏱️ Requires GHL platform fix
- ⏱️ Integration with external service failing
Do Not Escalate if:
- ✋ Configuration error (follow KB guides to fix)
- ✋ User training issue (educate user)
- ✋ Custom value not filled (fill it)
- ✋ Workflow logic error (fix workflow)
- ✋ Expected behavior (explain to user)
4.2 Escalation Checklist
Before escalating, gather:
1. Detailed Description
What exactly is not working?
Be specific and observable
❌ BAD: "Workflows are broken"
✅ GOOD: "B-007-WF-1.1 confirmation workflow not sending emails
after calendar bookings in Real Estate client accounts only"
2. Steps to Reproduce
Exactly how to make the issue happen
Example:
1. Load z.sc.Real-Estate-Base-2025-10-06-v1 into test account
2. Book calendar appointment for tomorrow 10 AM
3. Wait 2 minutes (when confirmation should send)
4. Check contact → No email sent
5. Check workflow logs → Workflow didn't trigger
3. What You've Tried
List troubleshooting steps already attempted
- Verified workflow published ✅
- Checked trigger conditions ✅
- Tested with fresh contact ✅
- Reviewed workflow logs - no errors ✅
- Compared with working account - same config ✅
4. Affected Scope
Who/what is impacted?
- Specific client: MCG Real Estate
- All RE clients: Yes (tested 3 accounts)
- Other industries: No (tested Prof Services - works fine)
- Since when: Started 2025-10-27 after v2 deployment
5. Supporting Information
Collect:
- Sub-account name/ID
- Workflow name/ID
- Contact example (email/phone)
- Screenshot of error (if visible)
- Workflow activity log export
- Recent snapshot/config changes
4.3 Escalation Channels
Internal Symphony Core:
- 🔧 Tech Lead: Platform/integration issues
- 👥 Account Manager: Client communication/expectations
- 📊 Operations: Process/workflow questions
External GHL:
- 💬 GHL Support Chat: Platform bugs, feature questions
- 📧 GHL Support Email: Complex technical issues
- 📚 GHL Community: Best practices, workarounds
Extendly:
- 📧 Extendly Support: Snapshot issues, module questions
- 📚 Extendly Documentation: Module functionality, updates
5. Preventive Maintenance
5.1 Weekly Health Checks
Every Week:
- Review workflow error logs (any failures?)
- Check email deliverability metrics (bounce rate < 5%?)
- Verify calendar connections active (no auth expired?)
- Scan for duplicate contacts (run Find Duplicates tool)
- Test critical workflows (booking, review request working?)
5.2 Monthly Audits
Every Month:
- Review all client custom values (any blanks?)
- Check domain SSL status (all active?)
- Verify phone number active (SMS still working?)
- Test GMB integration (review links functional?)
- Update snapshot version tracking (clients on current version?)
5.3 Before Major Changes
Before deploying new snapshot version:
- Test in z.sc Test environment first
- Validate all workflows function
- Check custom values populate correctly
- Verify calendar and integrations work
- Test with pilot client before full rollout
- Have rollback plan ready (archive old version)
5.4 Client Onboarding Validation
After loading snapshot into new client:
- ExtendlyOS form completed (all 98 values filled?)
- Domain connected and SSL active (pages load?)
- Email domain configured and verified (test email sent?)
- Phone number configured (test SMS sent?)
- Calendar connected (can book appointment?)
- GMB integrated (review link works?)
- Test critical workflows (lead capture → follow-up working?)
Complete Checklist: See KB-004:Section 5 for full post-onboarding validation
Quick Diagnostic Cheatsheet
Symptoms → Likely Causes → First Check
| Symptom | Likely Cause | First Check |
|---|---|---|
| Workflow not triggering | Published? Conditions? Re-entry? | Workflow status badge |
| Email not sending | No dedicated domain | Settings → Email Services |
| SMS not delivering | No country code | Contact phone format |
| Calendar no times | Calendar not connected | Settings → Calendar |
{{placeholder}} showing | Value not filled | Settings → Custom Values |
| Page not loading | Domain not connected | Settings → Domains |
| Duplicate contacts | Detection disabled | Settings → Contact Settings |
| No-show not tracked | Status not updated | Manually mark no-show |
| Review link broken | GMB not integrated | Settings → Integrations |
| Slow automation | High volume, rate limits | Workflow queue, spread load |
Related Knowledge Base Articles
Foundation:
- KB-002: Automation Ecosystem - How modules work together
- KB-005: Systems Integration - Technical architecture and advanced troubleshooting
Setup Guides:
- KB-003: Custom Values Deep Dive - Custom values troubleshooting (Section 4.5)
- KB-004: Client Onboarding Checklist - Setup procedures and validation
Visual Reference:
- KB-008: Visual Reference Guide - System diagrams and flowcharts
Document Information
- Version: 1.0 (Draft)
- Created: October 29, 2025
- Status: Draft - Ready for Review
- Estimated Word Count: ~5,000 words
- Estimated Page Count: ~20 pages
- Next Review: After team feedback
- Location:
06-team-training/platform-training/kb-007-decision-trees-troubleshooting.md
Author: Symphony Core Knowledge Management Team Contributors: Claude Code
End of KB-007: Decision Trees and Troubleshooting Guide