---
title: "Workflow Debugging Guide"
description: "Learn how to debug NodeTool workflows, inspect data between nodes, and troubleshoot errors."
canonical: https://docs.nodetool.ai/workflow-debugging
markdown: https://docs.nodetool.ai/workflow-debugging.md
product: NodeTool
source: https://github.com/nodetool-ai/nodetool/blob/main/docs/workflow-debugging.md
---

# Workflow Debugging Guide

This guide teaches you how to debug NodeTool workflows when they don't work as expected. You'll learn to inspect intermediate data, read error logs, and systematically isolate problems.

---

## Quick Debugging Checklist

When a workflow isn't working:

- [ ] Check node status colors (gray/yellow/green/red)
- [ ] Click on failed (red) nodes to see error messages
- [ ] Add Preview nodes after suspicious nodes
- [ ] Verify all required inputs are connected
- [ ] Check data types match between connections
- [ ] Review the console/logs for detailed errors
- [ ] Test problem nodes in isolation

---

## Understanding Node Status

Nodes display their execution status through border colors:

| Color | Status | Meaning |
|-------|--------|---------|
| **Gray** | Not started | Node hasn't been processed yet |
| **Yellow** | Running | Node is currently executing |
| **Green** | Completed | Node finished successfully |
| **Red** | Failed | Node encountered an error |
| **Blue outline** | Selected | Node is currently selected |

When a node fails (red), click it to see the error message in the properties panel.

---

## Using Preview Nodes

Preview nodes are your primary debugging tool. They show exactly what data is flowing through your workflow at any point.

### Adding Preview Nodes

1. Press **Space** to open the node search
2. Type "Preview" and select the Preview node
3. Connect the output you want to inspect to the Preview node
4. Run the workflow

### Preview Node Strategies

**After every major transformation:**
```
Input → Process → Preview(1) → Transform → Preview(2) → LLM → Preview(3) → Output
```

**Before and after suspicious nodes:**
```
... → Preview(before) → SuspiciousNode → Preview(after) → ...
```

**At branch points:**
```
        → Preview(A) → ProcessA
Input →
        → Preview(B) → ProcessB
```

### What Preview Shows

Preview nodes display data based on type:

| Data Type | Preview Display |
|-----------|-----------------|
| **Text/String** | Full text content, scrollable |
| **Image** | Rendered image with dimensions |
| **Audio** | Playable audio widget |
| **List** | JSON array with items |
| **Object/Dict** | Formatted JSON |
| **Number** | Numeric value |
| **Boolean** | True/False |

---

## Inspecting Workflow JSON

Every NodeTool workflow is stored as JSON. Inspecting this JSON can help debug complex issues.

### Exporting Workflow JSON

1. Open your workflow in the editor
2. Open the floating toolbar's **⋮** menu and choose **Download JSON** (also available in the command menu)
3. Save the `.json` file
4. Open in any text editor or JSON viewer

### Workflow JSON Structure

```json
{
  "id": "workflow_abc123",
  "name": "My Workflow",
  "description": "...",
  "nodes": [
    {
      "id": "node_1",
      "type": "nodetool.input.StringInput",
      "data": {
        "value": "Hello world"
      },
      "position": { "x": 100, "y": 100 }
    },
    {
      "id": "node_2", 
      "type": "nodetool.agents.Agent",
      "data": {
        "prompt": "...",
        "model": { "provider": "openai", "id": "gpt-4" }
      },
      "position": { "x": 300, "y": 100 }
    }
  ],
  "edges": [
    {
      "id": "edge_1",
      "source": "node_1",
      "sourceHandle": "output",
      "target": "node_2",
      "targetHandle": "text"
    }
  ]
}
```

### What to Look For

**Missing connections:** Check that `edges` correctly connect outputs to inputs

**Incorrect values:** Look at `data` for each node to verify settings

**Node types:** Ensure `type` matches expected node (typos happen in programmatic workflows)

**Position issues:** If nodes overlap or are off-canvas, check `position` values

---

## Reading Error Logs

### Desktop App Logs

**Enable debug logging:**
1. Open **Settings → Advanced**
2. Enable **Debug Logging**
3. Logs appear in the console panel (View → Developer Tools)

**Log location:**
- Windows: `%USERPROFILE%\.nodetool\logs\`
- macOS: `~/Library/Logs/NodeTool/` or `~/.nodetool/logs/`
- Linux: `~/.nodetool/logs/`

### CLI/Server Logs

When running NodeTool from command line:

```bash
# Verbose logging
nodetool serve --verbose

# Or set log level
nodetool serve --log-level debug
```

### Understanding Error Messages

**Common error patterns:**

```
Error: Type mismatch - cannot connect 'List[String]' to 'String'
```
→ Use a node to extract a single item from the list (e.g., `GetElement`)

```
Error: Required input 'prompt' is not connected
```
→ Connect something to the `prompt` input, or set a default value

```
Error: Model not found: 'gpt-4'
```
→ Check API key configuration in Settings → Providers

```
Error: CUDA out of memory
```
→ Use a smaller model, reduce batch size, or close other GPU applications

```
Error: Connection refused on localhost:7777
```
→ NodeTool server isn't running, or firewall is blocking

---

## Debugging Specific Issues

### LLM Not Responding

1. **Check model availability**
   - Open Models → Model Manager
   - Verify model is installed (local) or API key is set (cloud)

2. **Test with Preview**
   - Add Preview after the Agent/LLM node
   - Run and check if any output appears

3. **Check prompt**
   - Is the prompt template valid?
   - Are all template variables being filled?

4. **Verify connectivity**
   - For cloud models: check internet connection
   - For local models: check if Ollama/llama.cpp is running

### Image Generation Fails

1. **Check model installation**
   - Open Model Manager
   - Ensure Flux/Qwen Image/etc. is downloaded

2. **Verify VRAM**
   - Check GPU memory with `nvidia-smi`
   - Close other GPU apps if memory is low

3. **Inspect parameters**
   - Valid dimensions? (usually multiples of 8 or 64)
   - Reasonable step count? (20-50 typical)
   - Valid CFG scale? (5-15 typical)

4. **Add Preview before generation**
   - Confirm prompt text is correct
   - Check that conditioning inputs are valid

### RAG/Search Returns Nothing

1. **Verify collection exists**
   - Check that index workflow was run first
   - Collection name matches between index and search

2. **Check embedding model**
   - Same embedding model for index and search?
   - Model available and running?

3. **Test query**
   - Try a simpler query
   - Increase `top_k` to retrieve more documents
   - Check if documents were chunked appropriately

4. **Inspect indexed content**
   - Use Preview to see what was indexed
   - Check chunk sizes aren't too small/large

### Workflow Runs Forever

1. **Check for loops**
   - While NodeTool prevents circular connections, complex logic can create infinite loops
   - Look for conditional nodes that might never exit

2. **Monitor node status**
   - Which node is stuck on "running" (yellow)?
   - That node is the bottleneck

3. **Check network calls**
   - API timeouts can appear as hangs
   - Add timeout parameters where available

4. **Resource constraints**
   - Is the system running out of memory?
   - Is disk full (for large file operations)?

---

## Isolating Problems

### Binary Search Debugging

When you have a complex workflow and something's wrong:

1. **Disable half the workflow**
   - Disconnect nodes in the middle
   - Run first half only

2. **Check results**
   - Working? Problem is in second half
   - Broken? Problem is in first half

3. **Repeat**
   - Continue halving until you find the problem node

### Testing Nodes in Isolation

Create a minimal test workflow:

1. **New workflow** with just the suspicious node
2. **Add input nodes** with known good test data
3. **Add Preview/Output** to see results
4. **Run and verify**

If the node works in isolation, the problem is with the data it receives in the full workflow.

### Comparing Working vs Broken

If a workflow used to work:

1. **Export both versions** (working and broken) as JSON
2. **Diff the files** to see what changed
3. **Focus on changed nodes/edges**

```bash
diff working_workflow.json broken_workflow.json
```

---

## Debugging Tools Summary

| Tool | When to Use | How to Access |
|------|-------------|---------------|
| **Preview nodes** | See intermediate data | Space → search "Preview" |
| **Node click** | See error messages | Click red (failed) nodes |
| **Console/DevTools** | View detailed logs | View → Developer Tools |
| **JSON export** | Inspect workflow structure | ⋮ menu → Download JSON |
| **--verbose flag** | CLI debugging | `nodetool serve --verbose` |
| **Log files** | Historical debugging | `~/.nodetool/logs/` |

---

## Common Fixes

| Problem | Solution |
|---------|----------|
| "Type mismatch" | Add conversion node between incompatible types |
| "Not connected" | Wire up all required inputs |
| "Model not found" | Install model in Model Manager or configure API key |
| "Out of memory" | Use smaller model, reduce batch size, close apps |
| "Timeout" | Check internet, increase timeout setting |
| "Empty output" | Add Preview to find where data is lost |
| "Wrong format" | Use FormatText or conversion nodes |
| "Permission denied" | Check file paths and permissions |

---

## Getting More Help

If you're still stuck after debugging:

1. **Export your workflow** as JSON
2. **Take screenshots** of error messages
3. **Note your system info** (OS, GPU, RAM, NodeTool version)
4. **Ask on [Discord](https://discord.gg/WmQTWZRcYE)** with these details
5. **File a [GitHub issue](https://github.com/nodetool-ai/nodetool/issues)** for bugs

---

## Related Documentation

- [Troubleshooting Guide](troubleshooting.md) – Broader troubleshooting for common issues
- [Key Concepts](key-concepts.md) – Understanding nodes, edges, and data flow
- [Workflow Editor](workflow-editor.md) – Using the visual editor effectively
- [Cookbook](cookbook.md) – Working workflow patterns to learn from