5.11 Execution & Debugging

The Pop Workflow execution and debugging system provides complete real‑time monitoring, error tracing, data inspection, and step‑by‑step debugging capabilities.
Whether you are building a simple flow or a large automation pipeline, mastering debugging will greatly improve your development efficiency.

This chapter covers:

Workflow execution modes
Single‑node debugging
Execution logs
Error messages and stack traces
Common troubleshooting
Performance debugging tips

🚀 1. Execution Modes Overview

Pop provides three execution modes:

1. Run Entire Workflow

Click the top toolbar ▶ Run Workflow to execute the full pipeline.

Useful for:

Validating overall logic
Producing final outputs
Full checks before publishing an application

2. Run This Node (Single‑Node Debugging)

Right‑click a node → Run This Node.

Useful for:

Checking if node input is correct
Viewing node output
Debugging PSL scripts
Testing AI prompts

3. Auto‑Highlight Debug Mode

During execution:

The current node is highlighted in blue
Successful nodes turn green
Failed nodes turn red with an error icon

This gives you a clear visual execution path.

📜 2. Execution Log

The execution log (at the bottom of the canvas) is the core debugging tool.
For each node executed, Pop records:

Item	Description
Input	Received data (value / type / meta)
Output	Node output data
Time	Execution duration (ms)
Status	Success, failure, interrupted
Error	Message, stack trace, suggested fixes

You can:

Expand/collapse logs
Inspect raw JSON
Copy logs
Re‑run the node

🪜 3. Step‑by‑Step Debugging Techniques

When debugging complex workflows, use a node‑by‑node strategy:

Step 1: Check input from the entry node

Ensure the input fields, types, and paths are correct.

Step 2: Test key nodes individually

Right‑click → Run This Node
Validate scripts, AI logic, HTTP calls, file operations, etc.

Step 3: Observe data flow

Compare each node’s input and output with expectations using the log panel.

Step 4: Fix red (failed) nodes

Failed nodes display a red border with a tooltip explaining the issue.

❌ 4. Error & Exception Types

Pop automatically captures node‑level errors and categorizes them:

1. Configuration Errors

Examples:

No model selected in AI node
Missing HTTP URL
Required fields not filled

Fix: Check the right‑side properties panel.

2. Input Data Errors

Examples:

Upstream returned null
JSON structure mismatch
Unsupported file format

Fix: View upstream node logs.

3. PSL Script Errors

Example:

TypeError: Cannot read properties of undefined

Logs will display:

Error line
Expression causing issue
Suggestions

4. Runtime Errors

Examples:

HTTP request failed
AI model timeout
File path incorrect

Pop displays a full stack trace and guidance.

🧭 5. Debugging Tips

✔ 1. Output intermediate values

Use a dictionary node to print intermediate values:

{
  "debug_value": {{nodes.sn(5).output}}
}

✔ 2. Print via PSL

Inside a script node:

return {
  step: "after_clean",
  content: cleanedText,
};

✔ 3. Break large workflows into modules

Modules make debugging easier and more maintainable.

✔ 4. Use “Run This Node”

This is the fastest way to locate where something breaks.

✔ 5. Inspect raw JSON

Especially useful for HTTP/file nodes with nested data.

🧠 6. FAQ

❓ Node stays in “Waiting”?

Upstream node might have failed.
Check for red nodes.

❓ Why does my script return undefined?

Possible reasons:

Input port is empty
Incorrect field path (value / output / meta)
PSL script missing return

❓ AI node returns garbled text?

Check encoding or ensure UTF‑8 content.

❓ File nodes fail to read?

Use Pop’s virtual path, not absolute OS paths.

❓ Chart widget displays nothing?

Ensure the bound field is an array or valid JSON.

⚡ 7. Performance Debugging Tips

1. Avoid processing large files in PSL

Use specialized file nodes instead.

2. Avoid excessive loop nodes

Large arrays may slow execution.

3. Move complex logic into modules

Modules run efficiently and can be reused.

4. Reduce unnecessary AI context

Fewer tokens = faster performance.

🎯 8. Summary

Pop’s debugging tools aim to provide:

Visual full‑workflow tracing
Multi‑level debugging (full run / single node)
Detailed error feedback
Complete execution logs
A debugging‑friendly environment for large automation workflows

By mastering this chapter, you will be able to:

Quickly locate issues
Fix errors efficiently
Debug large workflows with ease
Build more stable and maintainable automation systems