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, and Failed. If you try to publish a version that is already Compiling, 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 was deleted, is no longer active (for example, it needs reauthorization), or is not available to this workspace. | Reselect a valid connection on that node. |
| This AI step's connection is no longer available. Pick a connection on its Model tile, or remove it to use Included AI. | The AI step's key was revoked, its connection was deleted or disconnected, or it was never shared with this workspace. | Open the step's Model tile and pick another connection, or clear it so the step runs on Included AI. |
| Trigger carries a connection it does not use that is no longer available — delete it and add it again in the editor. | The trigger takes no connection, but it still carries one that no longer exists. It has no connection field to fix. | Delete the trigger in the editor and add it again. |
| Action node carries a connection it does not use that is no longer available — delete it and add it again in the editor. | Same as above, on an action node. | Delete the action in the editor and add it again. |
| 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. | 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. |
Step "<name>" has <reference> typed as plain text in "<field>" | A data reference such as $trigger.fields.name was typed by hand, so the step sends those exact characters. This is a warning, not a blocker. | Open the step and choose Use data from a step? under the field, or pick the value from the data picker. |
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 is mid-flight: wait for it to settle before trying again.
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: a Switch case left unconnected
Say you added a Switch node named "Route by priority", gave it a selector, but never connected the second case to a downstream node. An unconnected case is a warning, not a publish error. When you publish:
- Publish succeeds and the version becomes Active.
- The toast reads "Workflow published with warnings" and lists
Switch "Route by priority" case "high-priority" (pathId: case-2) has no following node — the run ends when this path is taken. - 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 becomes Active and the toast no longer lists the warning.
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.
A successful compile moves the version straight to Active. Evals are advice: a failed eval does not stop you from publishing a workflow.
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 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 Compiling, wait for it to finish; if it is Inactive, activate it from the version toggle.
"{app} app keys need a permission for this step", "{app} needs your own app for this step" or "Client connection requests are not ready." A node needs an OAuth permission or a client-provided credential that is not satisfied yet. For the first two, the toast description names the step and the permission. Your own app keys lack the permission (or none are set up and turned on), or TaskJuice's app is not approved for it, so add app keys that include it. When the finding covers several apps, or mixes both kinds, the title reads "OAuth app keys need a permission" or "Your own app keys are required". Use the action the toast offers (Open OAuth app keys, Add your own app keys or Open Client requests), then publish again. See Which OAuth app a connection uses, and for the client-credential path, 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.