Fix errors that block publishing
Resolve compilation failures, invalid form references, and validation errors that stop a workflow version from going live.
When you publish a workflow version, TaskJuice compiles it and runs a set of validation checks. If anything is wrong, the version does not go live: it lands in the Failed status, or the publish is rejected with a specific error. This page shows you how to read each error and clear it.
When to use this
Use this page when:
- You clicked Publish (or flipped the activation toggle) and saw "Workflow compilation failed" or "Failed to publish workflow".
- The version badge shows Failed instead of Active.
- You got a message about a node, a connection, a form, or a duplicate name and the workflow refused to publish.
- The Run button stays disabled because the version never reached Active.
How publishing decides pass or fail
Publishing runs in this order, and it stops at the first failure:
- Permission check. You must be the workflow owner (or a super-admin). Otherwise you get a 403.
- Plan-clamp gate. If the workflow uses settings that exceed your workspace plan ceiling, publish is rejected before anything compiles.
- Compile. TaskJuice compiles the version. The status shows Compiling while this runs (the toggle polls every 2 seconds).
- Validation. The compiled version is checked against the publish-gate rules below. Errors block publishing; warnings do not.
- Activation. If everything passes, the version becomes Active and starts receiving live events.
A successful publish shows "Workflow published successfully". A failure shows "Workflow compilation failed" with the specific error as the description, and the version status becomes Failed.
A Failed version is still publishable. Fix the reported problem, then publish again. The publishable statuses are Draft, Inactive, Failed, and Eval failed. If you try to publish a version that is already Compiling or Evaluating, you get a 409 with "Workflow version is currently compiling. Please wait."
Fix validation errors
Validation errors name the rule that failed and, where possible, the node involved. Find your error message in the table, then apply the fix.
Trigger and structure
| Error message | What it means | Fix |
|---|---|---|
| Workflow must include at least one trigger node | The graph has no trigger. | Add a trigger as the first node. The Add node panel only offers triggers until one exists. |
| Trigger node should have outgoing edges | The trigger connects to nothing. This is a warning, not a blocker. | Connect the trigger to your first action so the run has somewhere to go. |
Node <id> is not connected to the workflow | A node is not reachable from the trigger. | Connect it with an edge, or delete it. |
| Node must have incoming edges | A non-trigger node has no incoming connection. | Draw an edge into it, or remove it. |
| End node must have incoming edges | An End node has nothing flowing into it. | Connect a node to the End node, or remove the End node. |
Duplicate node name: "<name>" | Two nodes share a display name. This is a warning. | Rename one of them so each node name is unique. |
Connections
| Error message | What it means | Fix |
|---|---|---|
| Trigger requires an account connection | The trigger needs a connected account and none is selected. | Open the trigger node and select a connection. |
| Action node authentication not hooked up. | An action that needs auth has no connection. | Open the action node and select a connection. |
Connection not found: <id> | The selected connection no longer exists. | Reselect a valid connection on that node. |
| Trigger node has an inactive connection | The selected connection is not active (for example, it needs reauthorization). | Reconnect the integration, then publish again. |
| Action node has an inactive connection | Same as above, on an action node. The optional-auth variant is a warning. | Reconnect the integration, then publish again. |
For the full reconnect flow, see Reconnect an integration.
Control-flow nodes
These come from the Branch, Switch, Loop, and Parallel configuration rules.
| Error message | Fix |
|---|---|
| Branch node must have at least 2 conditions | Add conditions until the Branch has at least 2 (the maximum is 8). |
| Branch node has fewer connected paths (X) than conditions (Y) | Connect an outgoing edge for every condition path. |
| Switch node must have a selector expression | Enter a selector expression on the Switch node. |
| Switch node must have at least one case | Add at least one case to the Switch. |
Duplicate pathId "<id>" found in cases | Give each Switch case a unique path. |
| matchMode must be one of: contains, loose, regex, strict | Pick a valid match mode on the Switch. |
| onNoMatch must be one of: default, error, skip | Pick a valid no-match behavior on the Switch. |
| maxIterations is required | Set a maximum iterations value on the Loop (range 1 to 1000). |
| Array path is required for array-type loops | Enter the dot-notation path to the array, for example data.items. |
| Condition expression is required for condition-type loops | Enter the exit condition expression on the Loop. |
| maxIterations cannot exceed 1000 | Lower the Loop maximum to 1000 or fewer. |
| Loop node has no incoming edges and will never be executed | Connect a node into the Loop, or remove it. |
| Parallel node must have at least 2 branches | Add branches until the Parallel has at least 2. |
Duplicate branchId "<id>" found | Give each Parallel branch a unique id. |
| Race completion mode requires at least 2 branches | Add a second branch, or change the completion mode. |
| Max concurrency cannot exceed branch count | Lower max concurrency to the number of branches or fewer. |
See Branch, Switch, Loop, and Parallel for how each node is configured.
Definitions and node config
| Error message | What it means | Fix |
|---|---|---|
| Trigger node must have a definition selected | The trigger has no app trigger chosen. | Pick a trigger definition in the trigger panel. |
Trigger definition not found: <id> | The chosen trigger no longer exists. | Reselect a valid trigger. |
Action definition not found: <id> | The chosen action no longer exists. | Reselect a valid action. |
| Configured node must have a nodeVersion specified | A node was saved without a version. | Reopen the node, reconfigure it, and save. |
Fix invalid form references
If your workflow uses a Form Submission trigger or a Display Form action, the form it points at must be published. Publishing is blocked when the referenced form is a draft, archived, or missing.
The toast title is "Some referenced forms are not published". The description names the node and a count, for example:
Node "form-intake-1" references a draft form and 2 other node(s).
Publish the form (or remove the node) and try again.To clear it, do one of the following for each named node:
- Publish the form it references, then publish the workflow again.
- Remove the form node from the workflow if you no longer need it.
If TaskJuice cannot resolve the specific node, you get the fallback: "One or more referenced forms are not published. Open each form node and publish the referenced form, or remove the node."
Resolve unpublishable states
Some failures are not a single bad field. Use this to tell them apart.
Read the failure toast
The toast description carries the exact reason. "Workflow compilation failed" with a message means the compiler ran and rejected something. A validation message (from the tables above) means a rule failed. A 409 ("currently compiling") means a publish is already in progress.
Check the version status badge
A version in Failed can be republished after a fix. A version in Compiling or Evaluating is mid-flight: wait for it to settle before trying again. Eval failed is also republishable.
Open the named node and fix it
Most validation errors name a node by id or name. Open that node, correct the configuration the message describes, and save. The header shows Unsaved changes until you save and Ready to publish once the draft is clean.
Test the node before republishing
Each node has a test button. Running it confirms the node is configured well enough to execute against real input. A node must be valid before the test fires. See Test a node and publish a version.
Publish again
With the fix saved, click Publish. On success the version becomes Active and the Run button is enabled.
A worked example: unconfigured Switch
Say you added a Switch node, gave it a selector, but never connected the second case to a downstream node. When you publish:
- The toast reads "Workflow compilation failed" with the description "Switch node case "high-priority" (pathId: case-2) has no connected edge".
- The version status flips to Failed.
- You open the Switch, draw an edge from the unconnected case to the node that should handle it, and save.
- You publish again. The version compiles and becomes Active.
Verify it worked
You succeeded when all of the following are true:
- The toast reads "Workflow published successfully" (or, for an activation, "Workflow compiled and activated successfully").
- The version badge shows Active, not Failed or Compiling.
- The Run button in the editor header is enabled. It is disabled for any version that is not Active.
If your workflow has blocking evaluation suites, a successful compile moves to Evaluating rather than straight to Active, and the publish returns without activating immediately. The version activates once evaluation passes. If evaluation fails, the status becomes Eval failed, which you can republish like any other failure.
Troubleshooting
"Failed to publish workflow" with no node named. This is the generic failure title; the real reason is in the toast description. If the description says the compiled plan could not be validated (for example "Steps must be an array" or "Missing or invalid entryStepId"), that points to an internal compiler problem rather than your configuration. Contact support with the workflow and version.
Publish keeps returning 409. The version is still Compiling or Evaluating from a previous attempt. Wait for the badge to settle, then publish again.
The Run button is greyed out even though publishing succeeded. Run is only enabled when the current version is Active. If the version is Evaluating, wait for it to finish; if it is Inactive, activate it from the version toggle.
"BYOC OAuth client required" or "Client connection requests are not ready." A node needs an OAuth scope or a client-provided credential that is not satisfied yet. Use the in-editor CTA the message offers (Open BYOC settings or Open Client requests) to supply it, then publish again. For the client-credential path, see Reconnect an integration.
The expression in a node field is rejected. Field-level expression errors (for example INVALID_SYNTAX or MISSING_NODE) come from the expression engine, not the publish gate. Fix the expression in the node, then republish. See Expressions for the alias and error reference.