Troubleshooting Guide
Solutions to common workflow issues
Table of Contents
Quick Troubleshooting Checklist
Start here! Most workflow issues can be resolved by verifying these essentials:
Workflow Setup
Common Mistakes to Avoid
Missing Connections
- Every node needs proper input/output connections
- Disconnected nodes won't execute
- Check for loose or missing connections
Incorrect Data Types
- Ensure output types match input expectations
- Use conversion nodes when needed
Missing Required Parameters
- Configure all required fields and relevant parameters for your use case in each node
- Workflows won't run with missing required fields or may generate inaccurate results with incomplete configuration
Node Configuration Issues
Incorrect node configuration is one of the most common causes of workflow failures. Here are specific configuration issues and how to fix them:
LLM Node Configuration Errors
File Variable Naming Issues
Problem: File variable configured incorrectly causes "Source '[entered source value]' not found" errors
- Correct:
input.source_data_1(withinput.prefix) - Wrong:
source_data_1(missing prefix) - Wrong:
{{input.source_data_1}}(don't use curly braces in file_variables field) - Multiple Sources: Use comma as delimiter:
input.source_data_1, input.source_data_2
Where to check:
- LLM node configuration → "Attached Files" field
- Agent configuration → File variable key must match (e.g.,
source_data_1) - All LLM nodes in workflow should use consistent naming
Solution: Always use input.source_data_1 format in LLM node file_variables field
Model Selection
Important: While a model is selected by default, you should choose the appropriate model for your specific use case
Best Practices:
- Review the default model and select one that matches your task requirements
- Consider model capabilities (reasoning, speed, cost) for each node's purpose
- Different nodes can use different models optimized for their specific tasks
Temperature Settings
What it does: Controls randomness in AI responses
- Low (0.0-0.3): Deterministic, consistent - use for data extraction and analysis
- Medium (0.4-0.7): Balanced - use for general tasks
- High (0.8-1.0): Creative, varied - use for content generation and brainstorming
Variable Assignment Node Issues
Source Field Errors
Problem: "Variable not found" or empty variables downstream
Correct Format:
llm_node_name.response(for LLM node output)decision_tree_node.category(for Decision Tree classification)loop_node.complete(for Loop node aggregated results)
Variable Naming Rules
Valid: Letters, numbers, underscores only
-
evaluation -
evaluation_questions -
project_plan_2024
Invalid:
-
evaluation-questions(hyphens not allowed) -
project plan(spaces not allowed) -
evaluation.questions(dots reserved for node.property syntax)
Return Response Node Problems
Template Syntax Errors
Problem: Variables show as empty or template doesn't render
Correct Template Syntax:
{{evaluation}},
{{evaluation_questions}},
{{project_plan}}Common Mistakes:
- Typo in variable name:
{{evalution}}instead of{{evaluation}} - Missing curly braces:
evaluationinstead of{{evaluation}} - Variable not saved: Referencing a variable that was never created with Save Variable node
Response Type Mismatches
Problem: Output format doesn't match response type setting
- Text: Use for plain text or markdown output
- JSON: Use when returning structured data - template must produce valid JSON
Error Handling
Proper error handling ensures your workflows handle unexpected situations gracefully and provide useful feedback.
Error Handling Strategies
Error Types
- Validation Errors: Invalid input data
- Processing Errors: Node execution failures
- Timeout Errors: Operations taking too long
Recovery Options
- Retry: Attempt the operation again
- Log and Continue: Record error and proceed
- Fail Gracefully: Stop execution with informative message
Variable Reference & Template Syntax
Understanding when and how to reference variables is critical for workflow success. Different contexts require different syntax:
Syntax Quick Reference
| Context | Correct Syntax | Example | Wrong Syntax |
|---|---|---|---|
| File Variables (LLM Node) | input.source_data_1 | Attached Files field: input.source_data_1 | {{input.source_data_1}}source_data_1 |
| Save Variable Source | node_name.response | Source: llm_1.response | {{llm_1.response}}llm_1 |
| Saved Variables in Templates | {{variable_name}} | Prompt: Analyze: {{evaluation}} | evaluation{{evaluation |
| Node Outputs in Templates | {{node_name.response}} | Template: {{llm_1.response}} | llm_1.response{{llm_1}} |
| If/Else Conditions | variable_name > 80 | Condition: confidence > 0.8 | {{confidence}} > 0.8"confidence" > 0.8 |
| Agent File Variable Key | source_data_1 | Key: source_data_1 (without input.) | input.source_data_1{{source_data_1}} |
Common Syntax Mistakes
Mistake 1: Using Curly Braces in Wrong Context
In LLM file_variables field: {{input.source_data_1}}
In Save Variable source field: {{llm_1.response}}
In If/Else condition: {{score}} > 80
In LLM file_variables field: input.source_data_1
In Save Variable source field: llm_1.response
In If/Else condition: score > 80
Rule: Only use {{}} in template fields (prompts, Return Response templates)
Mistake 2: Missing Input Prefix for Files
LLM Node file_variables: source_data_1
Result: "File not populated" error
LLM Node file_variables: input.source_data_1
Note: Agent configuration uses source_data_1 (without "input."), but LLM nodes use input.source_data_1
Mistake 3: Variable Name Typos
Problem: Variable names in templates must match EXACTLY what was saved
{{evalution}}instead of{{evaluation}}{{project-plan}}instead of{{project_plan}}{{evaluation_question}}instead of{{evaluation_questions}}(missing 's')
Solution: Copy variable names directly from Save Variable nodes to avoid typos
Mistake 4: Wrong Node Output Property
Different node types have different output properties:
| Node Type | Output Property | Example |
|---|---|---|
| LLM Node | .response | llm_1.response |
| Decision Tree Node | .category | classifier_1.category |
| Loop Node | .complete | loop_1.complete |
| Save Variable Node | Variable name directly | {{evaluation}} (not save_1.evaluation) |
Debugging Workflows
Debugging Techniques
- Test Incrementally: Run your workflow after adding each node
- Check Node Status: Look for error indicators on individual nodes
- Review Execution Logs: Examine detailed logs for error messages
- Isolate Problem Areas: Copy workflow and run only sections that work up to the point of failure
- Verify Data Flow: Check that data is being passed correctly between nodes
Common Debug Patterns
Workflow Execution Problems
Problems that occur when trying to execute your workflow:
Edit vs Run Mode Issues
Understanding the Modes
Problem: "Why can't I execute?" or "Why can't I edit?"
Solution:
- To Execute: Save workflow → Switch to Run mode → Select agent → Click Run Agent
- To Edit: Switch to Edit mode → Make changes → Save → Switch back to Run mode
- Important: Always save before switching modes
Agent Configuration Problems
Missing Agent Setup
Problem: Workflow won't run, no agent in dropdown
Solution - Create Agent:
- Switch to Edit mode
- Locate agent configuration section (below Node Palette on left)
- Set dropdown to "(New agent)"
- Configure:
- Name: Descriptive name (e.g., "RFI-RFP-Agent")
- Model: Select from dropdown
- Temperature: 0-1 (default: 0)
- Variables: Add file variables if workflow uses files
- Click "Save"
Variable Type Mismatches
Problem: File upload doesn't work or file not found
Cause: Agent variable configured as "Text" instead of "File"
Solution:
- Agent configuration → "+ Add Variable"
- Change type from "Text" to "File"
- Set key to match file variable name:
source_data_1(without "input." prefix) - Save agent configuration
File Variable Key Naming
Critical: Agent and LLM nodes use different naming conventions:
| Location | Syntax | Example |
|---|---|---|
| Agent Configuration → Variable Key | source_data_1 | No "input." prefix |
| LLM Node → file_variables | input.source_data_1 | With "input." prefix |
File Upload Issues
File Limits
- Max files per LLM node: 5 files
- Supported formats: Many file types including PDF, Word, Excel, CSV, images (for vision models), text files, and more
- Special handling: CSV/Excel files enable data analysis capabilities
File Not Reaching Node
Problem: File uploaded but LLM node can't access it
Checklist:
- Agent variable type is "File" (not "Text")
- Agent variable key matches:
source_data_1 - LLM node file_variables uses:
input.source_data_1 - File was uploaded in Run mode (not Edit mode)
- All LLM nodes in workflow use same file variable
input.source_data_1. Each LLM node receives the same uploaded file(s). Workflow Won’t Run
Checklist for Non-Running Workflows
- All nodes are connected properly
- Required parameters are filled in
- No disconnected nodes exist
- Data types match between connections
- No circular dependencies present
- Workflow has been saved
Real-World Examples from Tutorials
These are actual issues users encounter when following the First Workflow Tutorial. Each example includes the problem, cause, and solution:
Example 1: Empty Variables in Third LLM Node
"My third LLM node (rfi_rfp_project-plan) shows empty variables for {{evaluation}} and {{evaluation_questions}}"
Cause: Save Variable nodes (Steps 3 and 5 in tutorial) were skipped or misconfigured
What Happened:
- User configured the three LLM nodes correctly
- But forgot to add Save Variable nodes between them
- Variables
evaluationandevaluation_questionswere never created - Third LLM prompt references variables that don't exist
Solution:
- Add Save Variable node after first LLM node (rfi_rfp_data_extraction)
- Source:
rfi_rfp_data_extraction.response - Variable name:
evaluation
- Source:
- Add Save Variable node after second LLM node (rfi_rfp_questionnaire)
- Source:
rfi_rfp_questionnaire.response - Variable name:
evaluation_questions
- Source:
- Connect nodes properly: LLM → Save Variable → Next LLM
- Verify variable names match EXACTLY in prompt template
Example 2: File Not Found in Third LLM Node
"The rfi_rfp_project-plan node shows 'file not populated' in execution logs"
Cause: File variable inconsistency in Step 6 of the tutorial
What Happened:
- First two LLM nodes correctly use
input.source_data_1 - Tutorial Step 6 says to use
source_data_1(missinginput.prefix) - This inconsistency causes the third node to not receive the uploaded file
Solution:
- Correct configuration: Use
input.source_data_1in ALL three LLM nodes - Open third LLM node (rfi_rfp_project-plan)
- Change file_variables from
source_data_1toinput.source_data_1 - Save workflow and test again
input.source_data_1 format for file variables in LLM nodes. Example 3: Workflow Won't Execute
"When I click Run Agent, nothing happens" or "Can't find the Run Agent button"
Cause: Still in Edit mode or workflow not saved
What Happened:
- User built the workflow in Edit mode
- Tried to execute without switching to Run mode
Solution:
- Click the "Save" button (top of screen)
- Switch from "Edit" to "Run" mode using the toggle
- Left panel transforms to show agent interface
- Select your agent from dropdown (RFI-RFP-Agent)
- Upload your RFP/RFI document using the file attachment button
- Click the blue "Run Agent" button
Example 4: Return Response Shows Nothing
"Workflow completes but Return Response node output is empty or shows raw variable names"
Cause: Variable names in template don't match saved variable names
What Happened:
- User typed
{{evalution}}instead of{{evaluation}}(typo) - Or used
{{project-plan}}with hyphens instead of{{project_plan}}with underscores - Variable names must match EXACTLY (case-sensitive, spelling, punctuation)
Solution:
- Check Return Response node template matches these EXACT names:
{{evaluation}}{{evaluation_questions}}{{project_plan}}
- Verify each Save Variable node uses these exact names
- Look for typos: missing letters, extra spaces, wrong punctuation
- Copy-paste variable names from Save Variable nodes to avoid typos
Getting Help
Before Contacting Support
- Review this troubleshooting guide
- Check the Core Concepts documentation
- Try running example workflows to isolate the issue
- Collect error messages and execution logs
- Note the steps that led to the problem
Information to Provide
When requesting help, include:
1. Workflow Context
- Description: What you're trying to accomplish
- Tutorial/Example: Which tutorial or example you're following (if any)
- Workflow JSON: Export your workflow using the Import/Export feature
- Node count: How many nodes in your workflow
2. Reproduction Steps
- Exact steps taken before the issue occurred
- Which node the issue occurs at
- Whether issue is consistent or intermittent
- What you expected to happen vs. what actually happened
3. Error Information
- Error messages: Exact text from Activity log
- Execution Logs: Full logs from ">>" modal (copy/screenshot)
- Failed node name: Which node shows error
- Error timing: When in execution the error occurs
4. Configuration Details
- Screenshots: Workflow canvas showing all nodes and connections
- Node configuration: Screenshot of failed node's settings panel
- Agent configuration: Agent settings (model, temperature, variables)
- File details: If using files, what type/size/format
5. Environment
- Browser and version
- When the issue started (new workflow or existing that stopped working)
- Whether this workflow worked before