SuperPlane Troubleshoot

Decision-tree troubleshooting for SuperPlane canvas and execution problems.

Quick Diagnosis

Start here. What's the symptom?

Symptom	Jump to
Canvas exists but nothing happens	No Executions Starting
Execution starts but a node fails	Node Failure
Execution starts but a node is stuck	Node Stuck
Expression returns wrong value	Expression Problems
Merge node never fires	Merge Deadlock
Canvas update rejected	Canvas Validation Errors

Canvas exists but no executions appear when you expect them.

Check in order:

Is the trigger paused?
```
superplane canvases get <name>
```
Look for paused: true on the trigger node. Set to false and update.
Is the trigger configured correctly?
- Schedule: is the cron expression or interval correct?
- GitHub: does the repository match? Are the refs filters correct?
- Webhook: has the external system been configured to POST to the webhook URL?
Is the integration connected?
```
superplane integrations list
```
If the trigger uses an integration (e.g., github.onPush), confirm the integration ID is set and the connection is active.
Was the event actually sent?
```
superplane events list --canvas-id <id>
```
If events appear but no executions, the trigger received the event but filtering may have excluded it. Check trigger refs or other filters.
If no events appear at all, the external system isn't sending to SuperPlane. Check webhook configuration on the source side.

An execution started but a node shows Failed status.

superplane events list-executions --canvas-id <id> --event-id <eid>

Check the failed node's error message:

"integration is required" → The node needs an integration.id. See the superplane-integrations skill.
Permission/auth error → The integration's credentials are expired or lack permissions.
```
superplane integrations get <integration-id>
```
Reconnect the integration in the UI if needed.
Expression evaluation error → The expression references a missing field or has a syntax error. See Expression Problems.
HTTP error (4xx/5xx) → The external service returned an error. Check the response body in the execution details for specifics.
Timeout → The external service didn't respond in time. Check if the service is healthy independently.

A node shows Pending or Running for longer than expected.

Approval node → Waiting for human approval. Check the SuperPlane UI for pending approvals, or inspect the queue:
```
superplane queue list --canvas-id <id> --node-id <nid>
```
Time Gate → Holding until the allowed window. Check the timezone, allowedDays, startHour, endHour configuration. The execution will release when the window opens.
Wait node → Holding for the configured duration or timestamp. This is expected behavior.
Merge node → Waiting for all incoming edges. See Merge Deadlock.
External service slow → The integration component is waiting for a response. Check the external service's health.

Queue backed up → Multiple executions queued on the same node:

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

Clear stuck items if needed:

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

An expression returns the wrong value, nil, or causes an error.

Check node name casing: $['Node Name'] is case-sensitive. Run superplane canvases get <name> and compare the exact name field.
Check the field path: the upstream node may emit a different payload structure than expected. Inspect the execution output to see what was actually emitted.
Nil from missing field: if the upstream node didn't emit the expected field, the expression returns nil. Use ?? "default" for fallback values.
Type mismatch: Filter and If expressions must return a boolean. $['Node'].status (a string) is not a boolean — use $['Node'].status == "success".
Missing {{ }} delimiters: the value is treated as a literal string if not wrapped in expression delimiters.
Referencing a parallel node: you can only reference nodes that are upstream (connected by edges). If node A is parallel to node B, neither can reference the other. Add a Merge node first.

A Merge node never fires — execution stops.

Merge waits for all incoming edges to have a completed execution. If any upstream branch doesn't complete, Merge blocks forever.

Common causes:

A branch was filtered out: If a Filter or If node routed execution to the other channel, the Merge branch never receives an execution.
- Fix: ensure all branches that feed into Merge will always execute, or restructure to avoid the Merge dependency.
An upstream node failed: a failed node doesn't propagate to downstream nodes, so Merge never gets that branch's input.
- Fix: add error handling or restructure so failures are handled before the Merge.
An upstream node is stuck: see Node Stuck for that branch.
Wrong edge wiring: an edge is missing between an upstream node and the Merge.
```
superplane canvases get <name>
```
Verify that every branch intended to feed into the Merge has an edge with targetId pointing to the Merge node.

superplane canvases update rejects the YAML, or nodes show errorMessage/warningMessage.

Duplicate node names: each node's name must be unique within the canvas. The server sets a warningMessage on duplicates. Rename one of the nodes.
Missing required configuration: run superplane index components --name <component> to see required fields. Add the missing fields to the node's configuration.
Invalid edge channel: each component type has specific output channels. Using default on a Filter (which uses passed/failed) will fail. See the channel table:

Component Valid Channels

Filter passed, failed

If True, False

Approval approved, rejected

Everything else default
Missing integration.id: integration-backed nodes need integration.id. See the superplane-integrations skill.
Invalid YAML syntax: check for indentation errors, missing quotes around expressions with special characters, or malformed arrays.