Testing & Debugging

Testing and debugging are essential for building reliable chatflows. Flowise provides built-in tools to test, inspect, and troubleshoot your flows.

Testing Your Chatflow

Interactive Chat Interface

The quickest way to test your chatflow is using the built-in chat interface:

Open Chat Interface

Click the chat bubble icon in the bottom-right corner of the canvas. This opens a collapsible chat panel.

Start a Conversation

Type a message and press Enter
The message flows through your chatflow
Response appears in the chat interface
View streaming responses in real-time

Test Different Scenarios

Try various inputs to validate behavior:

Edge cases (empty input, very long input)
Different question types
Multi-turn conversations (if using memory)
Tool invocations (if using agents)
File uploads (if supported)

Clear Chat History

Click the eraser icon to reset the conversation and test from a fresh state.

The chat interface uses session storage. Each browser tab has an independent session, useful for testing multiple scenarios simultaneously.

Expanded Chat View

For more detailed testing, use the expanded chat interface:

Expand Chat

Click the expand icon (arrows) in the chat panel to open a full-screen dialog.

Advanced Features

The expanded view provides:

Larger conversation area
Message timestamps
Better visibility for long responses
File upload interface (drag-and-drop)
Voice input (if enabled)
Response time indicators

Monitor Performance

Watch for:

Response latency
Streaming behavior
Error messages
Tool execution logs (in agent flows)

Viewing Messages

Access the complete message history for analysis:

Open Settings Menu

Click the settings icon (gear) in the chatflow header.

View Messages

Select View Messages from the dropdown. This opens a dialog showing:

All conversations for this chatflow
Message timestamps
User and AI messages
Session IDs
Feedback ratings (if enabled)

Filter and Search

Filter by date range
Search message content
Filter by session ID
Export to CSV for analysis

Message Metadata

Each message includes valuable debugging data:

{
  "chatId": "unique-session-id",
  "role": "user", // or "assistant"
  "content": "What is the weather?",
  "createdDate": "2026-03-03T10:30:00Z",
  "chatflowId": "flow-id",
  "metadata": {
    "sessionId": "user-session-123",
    "chatType": "INTERNAL",
    "sourceDocuments": [...], // For RAG flows
    "agentReasoning": [...] // For agent flows
  }
}

Debugging Techniques

Visual Flow Inspection

Use the canvas to understand data flow:

Connection Validation
Node Validation
Flow Validation

Ensure connections are valid:

Green connections: Valid, type-compatible
Red/invalid: Type mismatch or missing required input
Orphaned nodes: Not connected to the flow (won’t execute)
Missing inputs: Nodes with unfilled required parameters

Orphaned nodes don’t cause errors but won’t execute. Ensure all nodes are part of the execution path.

Use the validation API to check the entire flow:

// Using the Agentflow component
const result = agentflowRef.current.validate()

if (!result.valid) {
  console.log('Errors:', result.errors)
  // Example errors:
  // - "Node 'chatOpenAI_0' missing required credential"
  // - "No output node found"
  // - "Circular dependency detected"
}

Testing Agent Flows

Agent flows require special attention:

Enable Agent Reasoning

In the chatflow configuration, enable Show Agent Reasoning to see:

Which tools the agent considers
Tool selection reasoning
Tool execution results
Intermediate steps
Final answer synthesis

Review Tool Descriptions

Poor tool descriptions are the #1 cause of agent failures:❌ Bad: “Calculator”✅ Good: “Useful for performing mathematical calculations. Input should be a valid mathematical expression like ‘2 + 2’ or ‘10 * 5’.”

The LLM uses tool descriptions to decide when and how to call tools. Be explicit about input formats and use cases.

Test Tool Execution

Test tools individually:

Ask questions that should trigger specific tools
Verify tool is called with correct parameters
Check tool returns expected results
Confirm agent uses results appropriately

Debug Agent Loops

If agent gets stuck in loops:

Set Max Iterations parameter (default: 10)
Review system message for conflicting instructions
Check if tools return valid, parseable output
Ensure tool descriptions don’t overlap (agent confusion)

Testing RAG Flows

Retrieval Augmented Generation requires validating both retrieval and generation:

Verify Document Upload

Use the Upsert button to upload documents
Check upsert history in settings menu
Verify document count in vector store
Review chunk sizes and overlap settings

Test Retrieval Quality

Ask questions and check retrieved documents:

Enable Return Source Documents in chain config
Review source documents in chat response
Verify relevance (right documents retrieved?)
Check similarity scores (above 0.7 is good)

Tune Retrieval Parameters

Adjust if retrieval is poor:

Top K: Number of documents to retrieve (default: 4)
Similarity Threshold: Minimum similarity score (0.0-1.0)
Chunk Size: Text splitter chunk size (500-1000)
Chunk Overlap: Overlap between chunks (50-200)

Debug Upsert Issues

If documents aren’t being found:

Check vector store credentials
Verify embedding model is same for upsert and retrieval
Review upsert history for errors
Test with simple, direct questions first

Common Issues and Solutions

No Response / Timeout

Symptoms: Chat doesn’t respond, or times out after 120 secondsCauses:

API key invalid or quota exceeded
Node misconfiguration (missing required params)
Network issues or API downtime
Infinite loop in agent

Solutions:

Check browser console for errors (F12)
Verify API credentials are valid
Test with simpler model (e.g., gpt-3.5-turbo)
Reduce Max Iterations on agents
Check API status pages (status.openai.com, etc.)

Wrong or Irrelevant Answers

Symptoms: LLM provides incorrect or off-topic responsesCauses:

Poor prompt engineering
Temperature too high (hallucinations)
Wrong documents retrieved (RAG)
Tool malfunction (agents)

Solutions:

Review and improve system message/prompt
Lower temperature (0.1-0.3 for factual tasks)
Add few-shot examples in prompts
Check retrieved documents (RAG flows)
Verify tool descriptions (agent flows)
Use more capable model (gpt-4 vs gpt-3.5)

Memory Not Working

Symptoms: Bot doesn’t remember previous messagesCauses:

Memory not connected to chain/agent
Different session IDs
Chat history cleared
Memory key mismatch

Solutions:

Verify memory node is connected
Check session ID consistency (should be same per user)
Use Session ID parameter or default to auto-generated
Ensure Memory Key matches chain’s expectation (chat_history)
Check memory type (Buffer vs Window vs Summary)

Tool Not Being Called

Symptoms: Agent ignores tools or uses wrong toolCauses:

Vague tool description
Model doesn’t support function calling
System message conflicts with tool use
Tool not connected properly

Solutions:

Improve tool descriptions (be very explicit)
Use Tool Agent instead of Conversational Agent (uses function calling)
Remove conflicting instructions from system message
Verify tool connections (check edge exists)
Test with simpler prompts that clearly need the tool

Rate Limiting / 429 Errors

Symptoms: “Rate limit exceeded” errorsCauses:

Too many requests to API
API tier limits hit
Concurrent requests exceed quota

Solutions:

Add rate limiting in chatflow configuration
Upgrade API tier/plan
Implement request queuing
Use caching to reduce redundant calls
Increase timeout between retries

Browser Developer Tools

Use browser DevTools for deeper debugging:

Console
Network Tab
Application Storage

Open browser console (F12) to see:

JavaScript errors
Network request failures
API response details
Validation errors

// Common console messages:

// API call details
"POST /api/v1/prediction/flow-id"

// Validation errors
"Node validation failed: Missing credential"

// Agent reasoning (if enabled)
"Agent selected tool: calculator"
"Tool result: 42"

Monitor API requests:

Open DevTools → Network tab
Send a chat message
Look for requests to /api/v1/prediction/
Click request to see:
- Request payload (your input)
- Response (LLM output)
- Headers (auth, content-type)
- Timing (latency)

Red requests indicate errors - click to see error details.

Check stored data:

DevTools → Application → Local Storage
Look for keys like {chatflowId}_INTERNAL
Contains chat history and session data
Clear to reset state

{
  "chatId": "session-123",
  "messages": [...],
  "timestamp": 1709467800000
}

API Testing

Test your chatflow via API for production-like scenarios:

Get API Endpoint

Click the API Code button in the chatflow header to see:

Prediction endpoint URL
Example request code (cURL, Python, JavaScript)
API key requirements

Test with cURL

curl -X POST https://your-flowise.com/api/v1/prediction/{flowId} \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What is the weather?",
    "overrideConfig": {
      "sessionId": "test-session-123"
    }
  }'

Test Advanced Features

Use overrideConfig to test:

{
  "question": "Test question",
  "overrideConfig": {
    "sessionId": "user-123",
    "vars": {
      "customVar": "value"
    },
    "temperature": 0.5,
    "returnSourceDocuments": true
  }
}

Performance Monitoring

Response Time Analysis

Track and optimize response times:

Identifying Bottlenecks

Common slow components:

LLM API calls: 2-10 seconds (largest factor)
Vector search: 100-500ms
Tool execution: Varies by tool (API calls can be slow)
Document processing: Depends on size

Optimization strategies:

Use streaming for perceived performance
Cache frequent queries
Use faster models (gpt-3.5-turbo vs gpt-4)
Reduce token limits
Optimize vector store (better indexing)

Token Usage Tracking

Monitor and control costs:

Check Message Logs

View token usage in message history:

Prompt tokens (input)
Completion tokens (output)
Total tokens per request

Optimize Token Usage

Set Max Tokens to reasonable limits
Use shorter system messages
Reduce Top K in RAG (fewer retrieved docs)
Use smaller context windows
Clear memory periodically (in long conversations)

Cost Estimation

Calculate approximate costs:

GPT-4: ~$0.03 per 1K prompt tokens, $0.06 per 1K completion tokens
GPT-3.5: ~$0.0015 per 1K prompt tokens, $0.002 per 1K completion tokens

Example: 500 prompt + 200 completion tokens with GPT-4
Cost = (500 * 0.03 / 1000) + (200 * 0.06 / 1000) = $0.027

Best Practices

Testing Workflow

Start simple: Test basic functionality first
Add complexity gradually: Add one node/feature at a time
Test each addition: Verify before adding more
Use version control: Export flows regularly as backups
Test edge cases: Empty input, very long input, special characters
Load test: Use API testing for production scenarios
Monitor in production: Track errors and performance

Debugging Workflow

Reproduce the issue: Find consistent steps to trigger
Isolate the problem: Remove nodes until issue disappears
Check basics first: Credentials, connections, required params
Read error messages: Browser console and API responses
Test incrementally: Fix one issue at a time
Document fixes: Add sticky notes explaining solutions

Next Steps

Variables & Expressions

Use dynamic values for advanced flows

API Reference

Integrate chatflows into your application

Deployment

Deploy and monitor in production

Best Practices

Optimization and production tips

Get Started

Core Concepts

Building Flows

Deployment

Configuration

Testing & Debugging

Testing Your Chatflow

Interactive Chat Interface

Expanded Chat View

Viewing Messages

Debugging Techniques

Visual Flow Inspection

Testing Agent Flows

Testing RAG Flows

Common Issues and Solutions

Browser Developer Tools

API Testing

Performance Monitoring

Response Time Analysis

Token Usage Tracking

Best Practices

Next Steps

Variables & Expressions

API Reference

Deployment

Best Practices

Build docs developers (and LLMs) love

Get Started

Core Concepts

Building Flows

Deployment

Configuration

​Testing Your Chatflow

​Interactive Chat Interface

​Expanded Chat View

​Viewing Messages

​Debugging Techniques

​Visual Flow Inspection

​Testing Agent Flows

​Testing RAG Flows

​Common Issues and Solutions

​Browser Developer Tools

​API Testing

​Performance Monitoring

​Response Time Analysis

​Token Usage Tracking

​Best Practices

​Next Steps

Variables & Expressions

API Reference

Deployment

Best Practices

Build docs developers (and LLMs) love

Testing Your Chatflow

Interactive Chat Interface

Expanded Chat View

Viewing Messages

Debugging Techniques

Visual Flow Inspection

Testing Agent Flows

Testing RAG Flows

Common Issues and Solutions

Browser Developer Tools

API Testing

Performance Monitoring

Response Time Analysis

Token Usage Tracking

Best Practices

Next Steps