Skip to main content

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​

  1. Troubleshooting Philosophy (5 min)
  2. Decision Tree: System Not Working (10 min)
  3. Common Issues and Solutions (25 min)
  4. Escalation Guide (5 min)
  5. Preventive Maintenance (5 min)

1. Troubleshooting Philosophy​

1.1 The Symphony Core Approach​

Core Principles:

  1. Systematic, Not Random: Follow decision trees, don't guess
  2. Document Everything: Record symptoms, tests, and solutions
  3. Test One Thing at a Time: Isolate variables
  4. Start Simple: Check obvious things first (is it plugged in?)
  5. 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:

  1. 60 seconds: Check the obvious (is workflow published? is domain connected?)
  2. 2 minutes: Review recent changes in sub-account
  3. 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:

  1. ✅ Workflow published (not in draft)?
  2. ✅ Trigger conditions met (right tags, right source)?
  3. ✅ Contact hasn't gone through before (GHL re-entry block)?
  4. ✅ Required custom values populated?
  5. ✅ 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:

  1. ✅ Dedicated domain configured (Settings → Email Services)?
  2. ✅ DNS records set (SPF, DKIM, DMARC)?
  3. ✅ Domain warmed up (gradual volume increase)?
  4. ✅ Email content professional (no spam triggers)?
  5. ✅ Test email to yourself successful?

SMS Quick Checks:

  1. ✅ Phone number purchased and active?
  2. ✅ Contact phone has country code (+1)?
  3. ✅ SMS content professional (no spam words)?
  4. ✅ SMS sending limit not reached?
  5. ✅ 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:

  1. ✅ Calendar connected and authorized?
  2. ✅ Availability hours set correctly?
  3. ✅ Timezone matches client location?
  4. ✅ No conflicting appointments blocking all slots?
  5. ✅ User assigned to calendar?
  6. ✅ 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:

  1. ✅ Custom value has a value (not blank)?
  2. ✅ Syntax is {{custom_values.field_name}} (no spaces)?
  3. ✅ Field name spelled exactly right (check Settings)?
  4. ✅ Template/page republished after value update?
  5. ✅ 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:

  1. ✅ Domain added in Settings → Domains?
  2. ✅ DNS A record and CNAME configured?
  3. ✅ SSL certificate shows "Active" (wait 24-48 hrs)?
  4. ✅ Funnel/page published (not draft)?
  5. ✅ 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:

  1. Workflow in draft mode
  2. Trigger conditions not met
  3. Contact already in workflow
  4. Workflow has errors
  5. 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:

  1. Multiple triggers firing simultaneously
  2. Workflow triggering itself (loop)
  3. Re-entry prevention not working
  4. 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:

  1. Wait step configured incorrectly
  2. Timezone issues
  3. Business hours logic broken
  4. 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:

  1. No dedicated domain
  2. DNS records missing/incorrect
  3. Domain not warmed up
  4. High sending volume
  5. Email content triggers spam filters

Solutions:

Step 1: Configure Dedicated Domain

Settings → Email Services → Dedicated Domain
- Add domain (e.g., sc.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:

  1. Phone number not configured
  2. Contact phone missing country code
  3. SMS content flagged as spam
  4. Account SMS limit reached
  5. 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:

  1. Appointment status not updated
  2. No-show workflow not connected
  3. 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:

  1. Form not connected to custom values correctly
  2. Form field mapping wrong
  3. 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​

Symptoms:

  • Review link shows error
  • Link doesn't open review form
  • Reviews not being captured

Root Causes:

  1. GMB not integrated
  2. Wrong review link format
  3. 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:

  1. Calendar sync interval
  2. Authorization expired
  3. 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:

  1. Duplicate detection disabled
  2. Different email formats
  3. Different phone formats
  4. 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​

SymptomLikely CauseFirst Check
Workflow not triggeringPublished? Conditions? Re-entry?Workflow status badge
Email not sendingNo dedicated domainSettings → Email Services
SMS not deliveringNo country codeContact phone format
Calendar no timesCalendar not connectedSettings → Calendar
{{placeholder}} showingValue not filledSettings → Custom Values
Page not loadingDomain not connectedSettings → Domains
Duplicate contactsDetection disabledSettings → Contact Settings
No-show not trackedStatus not updatedManually mark no-show
Review link brokenGMB not integratedSettings → Integrations
Slow automationHigh volume, rate limitsWorkflow queue, spread load

Foundation:

Setup Guides:

Visual Reference:


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