Flow won't publish

If clicking Publish in the Flow Builder returns an error, the issue is almost always related to flow structure or references.

Common causes

• A disconnected node with no outgoing link;
• A variable referenced in a node that does not exist in the context;
• An invalid or empty branch condition;
• A subflow deleted but still referenced by a trigger_subflow node;
• A transfer node without a valid destination number.

Steps to resolve

1. In the Flow Builder, click Validate. The canvas will show warnings in red.
2. Fix each warning before attempting to publish.
3. Verify every used variable is declared or available by default.
4. Confirm referenced subflows still exist and are published.
5. Try publishing again.

Validation via API

GET /api/v1/agents/{agent_id}/flows/{flow_id}/validate

The response indicates structural errors, invalid references, and dead-end paths. Correct all items before calling POST /api/v1/agents/{agent_id}/publish.