SuperPlane Monitor

Inspect, debug, and manage workflow executions.

Quick Reference

Verify CLI Is Installed

Before any debugging, confirm the CLI is available:

superplane whoami

If command not found: stop and tell the user to install the CLI from https://docs.superplane.com/installation/cli. Debugging requires the CLI to inspect events, executions, and queues.

If debugging will require canvas edits, detect mode first:

superplane canvases get <canvas_name_or_id> -o json | jq '.metadata.canvasVersioningEnabled'

• true: apply fixes with superplane canvases update --draft ..., then create/publish via superplane canvases change-requests ....
• false: apply fixes with superplane canvases update ... (no --draft); canvases change-requests is unavailable.
• Org override: if organization versioning is enabled, all canvases are effectively versioned.
• Org override: if organization versioning is disabled, canvases can still toggle versioning individually.

Debugging Workflow

1. Find the Canvas

superplane canvases list

2. List Recent Events

superplane events list --canvas-id <canvas_id>

Each event is a trigger firing that starts a run.

3. Trace the Execution Chain

superplane events list-executions --canvas-id <canvas_id> --event-id <event_id>

Look for:

• Failed — the node that errored
• Pending/Running — possibly stuck
• Skipped — bypassed by a branch (If/Filter)

4. Inspect a Node's History and Payloads

superplane executions list --canvas-id <canvas_id> --node-id <node_id> -o yaml

Check if failures are recurring. For expression errors, inspect the actual payload structure:

• rootEvent.data.data — the trigger's real event payload (the double .data is the event envelope wrapping the webhook payload)
• input — what the node received from its upstream node (also has { data, timestamp, type } envelope)
• resultMessage — the exact error, including which expression field was nil

Use these real payloads to fix expression paths rather than guessing from documentation.

For branching/channel issues, inspect outputs in execution YAML (not just top-level result):

• A node can show RESULT_PASSED while only emitting on a non-default channel (for example, failed)
• Confirm emitted channel names under outputs match edge wiring (success, failed, default, etc.)
• If downstream behavior looks inconsistent with events list-executions, trust the node's outputs block for routing truth

5. Fix and Re-run

Update the canvas, then trigger a new run from the UI or via a manual_run trigger.

For versioning-enabled canvases, use the change-request lifecycle:

superplane canvases update <name-or-id> --draft --file canvas.yaml
superplane canvases change-requests create <name-or-id> --title "Fix failing workflow"
superplane canvases change-requests publish <change-request-id> <name-or-id>

If publish is blocked, inspect with change-requests get and then use approve, unapprove, reject, reopen, or resolve as needed.

Common Failure Patterns

Auth Failure

Node fails immediately with permission error. Check:

superplane integrations list
superplane secrets list

Verify the integration is connected and the secret is valid.

Expression Error

Node fails referencing a missing field. Check:

• Node name matches exactly (case-sensitive) in $['Node Name']
• Upstream node actually emits the expected field
• Root payload contains the expected data

Stuck Queue

Executions pile up without progressing:

superplane queue list --canvas-id <id> --node-id <nid>

Causes: node is paused, Approval waiting for human input, Time Gate holding, external service unresponsive.

Clear stuck items:

superplane queue delete --canvas-id <id> --node-id <nid> --item-id <iid>

Merge Never Fires

Merge waits for ALL incoming edges. If one branch is stuck, filtered out, or failed, Merge blocks. Check every upstream branch.

When to Use Other Skills

Documentation

For agents that can fetch URLs, the full SuperPlane docs are available in LLM-friendly format:

• Compact index: https://docs.superplane.com/llms.txt
• Full content: https://docs.superplane.com/llms-full.txt