​

Troubleshooting Guide

​

Before You Start

1. Check the execution log first
   • Go to your workflow
   • Click “Executions” or “History”
   • Find the failed run
   • See which action failed and why
2. Look at the error message
   • What does it say exactly?
   • See Error Messages Reference
3. Verify your data
   • Does the object exist in HubSpot?
   • Are variable values what you expect?

​

Workflow Won’t Run

​

Problem: Click “Run” but nothing happens

1. Is workflow saved? Look for “Saved” indicator
2. Are there actions? Empty workflow won’t run
3. Browser console errors? Open developer tools (F12)

1. Save workflow first
2. Add at least one action
3. Try different browser
4. Refresh page and try again

​

Problem: Webhook doesn’t trigger workflow

1. Webhook URL correct? Copy fresh URL from Agent.AI
2. HubSpot workflow active? Check it’s turned on
3. Test record matches trigger? Verify trigger conditions

1. In Agent.AI: Copy webhook URL
2. In HubSpot: Paste exact URL in webhook action
3. Activate HubSpot workflow
4. Create test record that matches trigger
5. Check Agent.AI executions for received webhook

​

Problem: Scheduled workflow not running

1. Schedule active? Verify schedule is enabled
2. Correct timezone? Check schedule time matches your timezone
3. Recent runs? Look in execution history

1. Verify schedule is turned on
2. Check schedule time is correct
3. Test manually first to ensure workflow works
4. Wait for next scheduled time

​

Connection Issues

​

Problem: “HubSpot not connected”

• Any HubSpot action fails
• Error says “not connected” or “no credentials”

1. Go to Settings → Integrations
2. Find HubSpot
3. Click Connect
4. Log in to HubSpot
5. Click Authorize
6. Return to workflow and try again

​

Problem: “Insufficient permissions” error

• Workflow fails on HubSpot action
• Error mentions “scope” or “permission”

1. Go to Settings → Integrations
2. Disconnect HubSpot
3. Reconnect HubSpot
4. Grant more permissions when prompted
5. Check permissions you need in OAuth Scopes
6. Try workflow again

• Read contacts: crm.objects.contacts.read
• Write contacts: crm.objects.contacts.write
• Read deals: crm.objects.deals.read
• Write deals: crm.objects.deals.write

​

Problem: Works for you but not for other users

• Your runs succeed
• Other team members get errors
• Error says “not connected” or “no permissions”

1. Each user: Go to Settings → Integrations
2. Each user: Connect their HubSpot account
3. Each user: Grant permissions
4. Workflow will use their credentials when they run it

​

Search/Lookup Issues

​

Problem: “Object not found” error

• Lookup action fails
• Error says “not found” or “does not exist”

1. Object ID correct? Check execution log
2. Object exists? Look in HubSpot
3. Right object type? Contact vs. Deal vs. Company

1. View execution log to see exact ID used
2. Search HubSpot for that ID
3. If doesn’t exist: Use Search action first to get valid ID
4. Verify variable has correct value

• ❌ Hardcoded ID: object_id=123 (might not exist)
• ✅ From search: object_id={{current_deal.hs_object_id}}

​

Problem: Search returns no results

• Search action succeeds but returns empty list []
• Expected results but got none

1. Filters too restrictive? Try removing some
2. Data exists in HubSpot? Check manually
3. Property names correct? Check spelling

1. Start with no filters - get all results
2. Add filters one by one
3. Check each filter value matches HubSpot data
4. Verify property names are exact (lowercase, underscores)

1. Remove all filters
2. Run search
3. If results: Filters were wrong
4. If no results: Object type or permissions issue

​

Problem: Can’t find property in picker

• Click ”+ Add Property” but can’t find property
• Property exists in HubSpot but not in Agent.AI

1. Custom property not synced yet
2. Wrong object type
3. Property name different

1. Wait a few minutes and refresh
2. Verify object type matches (contact property on contacts, not deals)
3. Check internal property name in HubSpot settings
4. Type exact internal name manually

​

Variable Issues

​

Problem: Variable shows as empty/undefined

• Variable picker shows variable but value is empty
• Error says “undefined” or “cannot read property”

1. Click on previous action
2. See what it returned
3. Check if variable was created

1. Previous action failed - Variable never created
2. Previous action returned nothing - Valid but empty
3. Wrong variable path - Using wrong property name

1. If previous action failed: Fix that action first
2. If returned empty: Add If Condition to check before using
3. If wrong path: Check execution log for correct structure

• ❌ Wrong: {{contact.email}} (missing .properties.)
• ✅ Correct: {{contact.properties.email}}

​

Problem: Can’t use loop variable outside loop

• Variable current_deal not available after End Loop
• Error says “variable not found”

1. Use loop variable only between For Loop and End Loop
2. If you need value after loop: Create new variable inside loop

1. For Loop (loop through deals, current_deal)
2.   Set Variable: last_deal_id = {{current_deal.id}}
3. End Loop
4. Can use {{last_deal_id}} here (NOT {{current_deal}})

​

Problem: Variable not updating in loop

• Counter stays at 0
• Total not increasing

1. Initialize variable BEFORE loop: counter = 0
2. INSIDE loop: Update same variable: counter = {{counter}} + 1
3. Variable name must match exactly

​

Update Issues

​

Problem: Update action doesn’t change anything

• Update action succeeds
• But HubSpot record unchanged

1. Correct object ID? Might be updating wrong record
2. Property name correct? Check spelling
3. Value valid? Check type matches property

1. Check execution log - which record was updated?
2. Go to that record in HubSpot
3. Check if property exists and is editable
4. Try updating manually in HubSpot

• Updating contact 123 but looking at contact 456
• Property name typo
• Read-only property
• Value wrong type (text in number field)

​

Problem: “Cannot update property” error

• Update fails with “cannot update” or “read only”

1. System property (HubSpot controlled)
2. Property doesn’t exist
3. Missing write permission

1. Check if property is system-managed (can’t update)
2. Verify property exists in HubSpot settings
3. Grant write permissions for that object type
4. Use different property

• createdate
• hs_object_id
• hs_lastmodifieddate

​

Timeline/Engagement Issues

​

Problem: Timeline event not appearing

• Create Timeline Event succeeds
• Event not in HubSpot timeline

1. Right record? Check object ID
2. Timeline filters? Clear filters in HubSpot
3. Event type exists? For custom events

1. Check execution log for object ID updated
2. Go to that exact record in HubSpot
3. Clear all timeline filters
4. Refresh page
5. For custom events: Create event type in HubSpot settings first

​

Problem: “Timeline events not available” error

• Create Timeline Event fails
• Error about availability or tier

1. Upgrade to Professional or Enterprise
2. OR use Create Engagement (notes) instead
3. Notes work on all tiers

​

Problem: Engagement creation fails

• Create Engagement fails
• Error about associations or type

1. Associations field filled? Required
2. Format correct? contact:{{contact_id}}
3. Engagement type valid? note, call, email, meeting, task

1. Add associations: At least one required
2. Use format: object_type:object_id
3. Check engagement type spelling (lowercase, no plural)

​

Loop/Condition Issues

​

Problem: Loop not running

• For Loop action runs but actions inside don’t

1. List is empty
2. Variable doesn’t exist
3. Not a list/array

1. See what “loop through” variable contains
2. If [] (empty array): No items to loop through
3. If not an array: Can’t loop through it

1. Check previous action returned results
2. Add If Condition to check list not empty first
3. Verify variable is actually a list

​

Problem: If Condition always TRUE (or always FALSE)

• Actions always run (or never run)
• Condition not evaluating correctly

1. Variable values - Check execution log
2. Condition syntax - Write in plain English
3. Property path - Is it correct?

1. Test with simple condition: 5 > 3 (should be true)
2. Check variable actually exists
3. View execution log to see variable values
4. Rewrite condition more simply

• ✅ Good: {{deal_amount}} > 10000
• ✅ Good: The email is not empty
• ❌ Complex: {{deal.properties.amount}} > 10000 AND {{deal.properties.stage}} equals "proposal" AND ... (break into multiple if statements)

​

Problem: Missing End Condition error

• Error says “End Condition required”
• Workflow won’t save

1. After For Loop: Add End Condition
2. After If Condition: Add End Condition
3. After Else Condition: Add End Condition

For Loop
  Action inside loop
End Condition

If Condition
  Action if true
Else Condition
  Action if false
End Condition

​

Webhook Issues

​

Problem: Webhook data not arriving

• Webhook triggers workflow
• But variables are empty

1. Go to HubSpot workflow
2. Check webhook action
3. Verify JSON payload format

1. Include _hubspot_portal: "_hubspot_portal": "{{portal.id}}"
2. Include data you need: "contact_id": "{{contact.hs_object_id}}"
3. Test HubSpot workflow
4. Check Agent.AI execution log to see what was received

​

Debugging Workflow

​

1. Identify Where It Failed

1. Open execution log
2. Find first red/failed action
3. That’s where to focus

​

2. Check Variable Values

1. Look at action before failure
2. See what variables were created
3. Verify values are what you expect

​

3. Simplify and Test

1. Remove variables, use hardcoded test values
2. Test action in isolation
3. Once working, add variables back

​

4. Verify in HubSpot

1. Check object exists
2. Check property exists
3. Try manual action in HubSpot

​

5. Check Permissions

1. Go to Settings → Integrations
2. Verify HubSpot connected
3. Check OAuth Scopes

​

6. Test Step by Step

1. Run workflow up to failing action
2. Fix that action
3. Continue to next action
4. Repeat until workflow completes

​

Getting Help

1. Check execution log - Screenshot the error
2. Note exact error message - Copy full text
3. Document what you tried - List steps taken
4. Describe expected vs actual - What should happen vs what happens
5. Share workflow config - Screenshots of action settings

• Which action failed
• Error message
• Variable values from execution log
• HubSpot object ID (if relevant)
• What you expected to happen

​

Related Resources

• Error Messages - Error explanations
• OAuth Scopes - Permission requirements

• HubSpot Setup - Connection setup
• Webhook Triggers - Webhook debugging
• Template Variables - Variable syntax

• Variable System - How variables work
• Action Execution - Execution flow