debug Block

The debug block displays selected message properties in the debug sidebar tab and optionally the runtime log. By default it displays msg.payload, but can be configured to display any property, the full message or the result of a JSONata expression.

Overview

The debug sidebar provides a structured view of the messages it is sent, making it easier to understand their structure. This block is essential for troubleshooting workflows and understanding how data flows through your system.

JavaScript objects and arrays can be collapsed and expanded as required. Buffer objects can be displayed as raw data or as a string if possible.

Configuration Options

Output Selection

Complete msg object: Display the entire message object
msg.payload: Display only the payload property (default)
msg.topic: Display only the topic property
Selected property: Display a specific message property
JSONata expression: Use JSONata expression to select specific data

Output Destinations

Debug sidebar: Show messages in the debug panel (default)
Runtime log: Send messages to the system log
Status text: Show short message preview under the node (32 characters)

Message Filtering

Node output: Enable/disable output using the button on the node
Message limit: Control how many messages to display

The debug sidebar provides detailed information alongside each message:

Timestamp: When the message was received
Source node: Which node sent the message (clickable to locate in workspace)
Message type: The type of data in the message
Structured view: Expandable/collapsible view of complex objects

Common Use Cases

Basic Debugging

Monitor message flow through your workflow:

{
  "payload": "Debug: Document processed successfully",
  "timestamp": 1640995200000,
  "_msgid": "abc123"
}

Object Structure Analysis

Inspect complex data structures:

{
  "payload": {
    "document": {
      "text": "Extracted text...",
      "confidence": 0.95,
      "pages": 3
    },
    "metadata": {
      "filename": "invoice.pdf",
      "size": 245760
    }
  }
}

Error Tracking

Monitor error conditions and exceptions:

{
  "payload": {
    "error": "OCR processing failed",
    "details": "Unsupported file format",
    "retry_count": 2
  },
  "topic": "error"
}

Best Practices

Development

Place debug blocks at key points in your flow to monitor data transformations
Use descriptive names for debug blocks to identify their purpose
Enable debug output only when needed to avoid clutter

Production

Disable or remove debug blocks that are not actively needed
Use status text output for lightweight monitoring
Consider using runtime log output for persistent debugging

Performance

Too many active debug blocks can impact performance
Use the enable/disable button to control output
Limit the number of messages displayed in complex flows

Tips

Click on the source node ID in the debug sidebar to highlight the node in the workspace
Use JSONata expressions to extract specific data from complex messages
The debug sidebar automatically formats JSON for easy reading
Buffer data can be viewed as both raw bytes and decoded strings
Collapse large objects in the sidebar to focus on relevant data

Notes

The debug block is one of the most important tools for workflow development
Messages appear in real-time as they flow through the block
The sidebar maintains a history of recent messages for analysis
Debug output can be cleared using the sidebar controls

debug