Decision Site

Search documentation

Search for pages in the documentation

Common Issues

Solutions to frequently encountered problems

This page covers solutions to frequently encountered problems in Agents.

Workflow Not Triggering

Symptoms

  • Workflow never runs
  • No executions appear
  • Events seem to be ignored

Causes and Solutions

Workflow Not Released

Check: Workflow status shows "Draft" instead of "Active"

Solution:

  1. Open the workflow editor
  2. Click "Release"
  3. Confirm the release

Wrong Event Type

Check: Event type doesn't match expected events

Solution:

  1. Verify the trigger event type
  2. Ensure it matches when you expect the workflow to run
  3. For meetings, check if you need MEETING_ENDED vs MEETING_ENDED_FOR_DEAL_ROOM

Trigger Rules Filtering Events

Check: Trigger has filter rules that exclude events

Solution:

  1. Review trigger configuration
  2. Check any filter conditions
  3. Temporarily remove filters to test

No Matching Events

Check: No events have occurred since release

Solution:

  1. Use MANUAL trigger to test
  2. Wait for next real event
  3. Verify events are being generated

Organization Mismatch

Check: Events are for a different organization

Solution:

  1. Verify workflow is in correct organization
  2. Check user permissions

Verification Steps

  1. Check workflow is released and Active
  2. View workflow trigger configuration
  3. Check execution list for any attempts
  4. Use manual trigger to test

Node Execution Failures

Symptoms

  • Node shows error status
  • Workflow stops at a specific node
  • Error messages in execution log

Common Causes

Timeout

Error: "Execution timed out"

Causes:

  • Operation takes too long
  • External service slow
  • Too much data to process

Solutions:

  • Simplify the operation
  • Use summary instead of full transcript
  • Check external service status
  • Consider splitting into multiple nodes

Invalid Configuration

Error: "Invalid configuration" or validation errors

Causes:

  • Missing required fields
  • Invalid values
  • Template syntax errors

Solutions:

  • Review all required fields
  • Check for typos in configuration
  • Validate Liquid templates
  • Verify CEL expressions

Missing Input Data

Error: "Property not found" or null errors

Causes:

  • Upstream node didn't produce expected output
  • Data structure different than expected
  • Conditional path skipped a node

Solutions:

  • Check upstream node output
  • Add null checks to conditions
  • Verify data flow through workflow

Retry Exhaustion

Error: "Max retries exceeded"

Causes:

  • Persistent failure condition
  • External service down
  • Rate limiting

Solutions:

  • Check external service status
  • Review error from first attempt
  • Increase retry limit if appropriate
  • Add longer backoff

Integration Problems

Symptoms

  • Integration nodes fail
  • Authentication errors
  • "Connection failed" messages

HubSpot Issues

OAuth Token Expired

Error: "Invalid access token" or "401 Unauthorized"

Solution:

  1. Go to Settings → Integrations
  2. Disconnect HubSpot
  3. Reconnect with fresh OAuth

Missing Permissions

Error: "Insufficient permissions"

Solution:

  1. Review required HubSpot scopes
  2. Reconnect with correct permissions
  3. Verify HubSpot user has admin access

Object Not Found

Error: "Object not found" or "404"

Causes:

  • Deal/contact ID is invalid
  • Object was deleted
  • Wrong object type

Solution:

  • Verify the object ID exists in HubSpot
  • Check object type matches

Salesforce Issues

Session Expired

Error: "Session expired or invalid"

Solution:

  1. Reconnect Salesforce integration
  2. Ensure Salesforce user account is active

Field Access Denied

Error: "Field not accessible"

Solution:

  1. Check Salesforce field-level security
  2. Ensure connected user has field access
  3. Use different field if restricted

Slack Issues

Channel Not Found

Error: "Channel not found"

Causes:

  • Channel ID is wrong
  • Bot not added to channel
  • Private channel access

Solution:

  1. Verify channel ID
  2. Add Slack bot to the channel
  3. Use channel picker if available

Rate Limited

Error: "Rate limited" or "429"

Solution:

  1. Add Wait nodes between messages
  2. Reduce message frequency
  3. Batch multiple notifications

AI Node Issues

Symptoms

  • AI output is wrong
  • Parsing errors
  • Unexpected results

Common Problems

Output Parse Failure

Error: "Failed to parse output" or type mismatch

Causes:

  • AI response doesn't match return type
  • Inconsistent output format

Solutions:

  • Add explicit format instructions to prompt
  • Use simpler return type
  • Include examples in prompt
  • Try higher model tier

Hallucination

Symptoms: AI includes information not in input

Solutions:

  • Add "Only include information from the provided content"
  • Be more specific about sources
  • Use "If not mentioned, say 'Not discussed'"

Too Long / Too Short

Symptoms: Output length not as expected

Solutions:

  • Add explicit length constraints
  • "Maximum 3 bullet points"
  • "Exactly 2-3 sentences"
  • "Under 100 words"

Wrong Focus

Symptoms: AI focuses on wrong aspects

Solutions:

  • Be more specific about what to include/exclude
  • Add "Focus on:" section
  • List items in priority order
  • Add "Do not include:" section

Model Tier Too Low

Symptoms: Poor quality for complex tasks

Solutions:

  • Upgrade to medium or high tier
  • Simplify the task
  • Break into multiple simpler prompts

AI Timeout

Error: "AI request timed out"

Causes:

  • Input too large
  • Complex task
  • Model overloaded

Solutions:

  • Use transcript summary instead of full transcript
  • Simplify prompt
  • Reduce input size
  • Try at different time

Data Flow Issues

Symptoms

  • Wrong data reaching nodes
  • Missing data in output
  • Unexpected null values

Common Problems

Referencing Wrong Node Output

Cause: Using json when data is from different step

Solution:

  • Use steps.nodeName.value for specific nodes
  • Check data flow in execution log
  • Verify node connections

Array vs Single Item

Cause: Expecting array but getting item, or vice versa

Solutions:

  • Check node variant (per-item vs batch)
  • Use Select Many to flatten arrays
  • Use proper Liquid iteration

Null in Chain

Cause: Null value breaks property chain

Solutions:

  • Add null checks in conditions
  • Use If nodes to handle null cases
  • Provide defaults

Data Lost Between Nodes

Cause: Node doesn't pass through all data

Solutions:

  • Check what the node outputs
  • Use Zip to combine data
  • Use Broadcast to attach context

Performance Issues

Symptoms

  • Workflows take too long
  • Timeouts
  • High costs

Solutions

Reduce Input Size

liquid
// Use summary instead of full transcript
{{ json.callRecording.transcriptSummary }}

Use Appropriate Model Tier

TaskTier
Simple classificationLow
Standard analysisMedium
Complex reasoningHigh

Optimize Workflow Structure

  • Remove unnecessary nodes
  • Combine operations where possible
  • Use parallel branches effectively

Add Caching

  • Don't re-process unchanged data
  • Store results for reuse
  • Use conditional execution

Release Issues

Can't Release Workflow

Causes:

  • Validation errors in workflow
  • Disconnected nodes
  • Missing required configuration

Solution:

  1. Check for validation errors
  2. Ensure all nodes are connected
  3. Review required fields in each node
  4. Check trigger configuration

Release Doesn't Take Effect

Causes:

  • Old version still Active
  • Cache issues
  • Timing

Solution:

  1. Verify workflow version status is Active
  2. Wait a few minutes
  3. Check which version is Active
  4. Try releasing again

Recovery Steps

General Recovery Process

  1. Identify the issue - Check execution logs
  2. Understand the cause - Review error message
  3. Fix the configuration - Update workflow
  4. Test the fix - Use manual trigger
  5. Release - Make the fixed version Active
  6. Monitor - Watch next few executions

Recovering from DLQ

  1. Fix the root cause first
  2. Review DLQ messages
  3. Retry messages if appropriate
  4. Discard if obsolete

Rolling Back

  1. Identify last working version
  2. Release that version
  3. Monitor to confirm fix
  4. Investigate issue in new version

Related