Troubleshooting

The most common failures, and the one-line fix.

The workflow doesn't fire

• It's paused. New workflows are created with is_active: false. Activate with PUT /workflow/:slug/toggle.
• The trigger doesn't match. field_changed needs one of its watched_fields to actually change; status_changed needs the field to land on to_status (and from from_status if set). Check GET /workflow/:slug/executions — a non-matching run is logged as skipped with a filter_reason.
• An action caused it. A workflow's own CRM write is tagged sourceType: "automation" and is deliberately not re-evaluated (loop prevention). A → B chains that expect re-triggering won't fire.
• Cache lag. Active workflows are cached ~5 min; a just-activated workflow may take a moment. Editing/toggling invalidates the cache.

400 on activate — SESSION_NOT_LINKED_TO_OBJECT

A message-triggered workflow that reads or writes a CRM record (e.g. update_field on same record, or send_message with phone_field_slug) needs its messaging session linked to an object, so an incoming chat resolves to a record. The error lists unlinkedSessionSlugs[]. Link the session to Contacts (or another object), or make the workflow reply-only. Preview this with POST /workflow/meta/validate-session-link before saving.

400 on create/update — relative-date condition

A within_next / within_past / on_date filter (or a scheduled reminder) must point at a date/datetime field and needs an amount > 0 and a unit. Date-only fields accept only the days unit; datetime fields accept minutes | hours | days. The trigger must also target an object.

400 — "Maximum 50 workflows per workspace"

The workspace hit MAX_WORKFLOWS_PER_WORKSPACE. Delete or consolidate workflows.

403 Forbidden

Authenticated but your role lacks the route: workflow.read (list/read), workflow.create, workflow.update (toggle/retry/approve), workflow.delete. See Authorization.

An execution is failed

Open GET /workflow/executions/:id and read error_message:

• send_message / send_template — the messaging session is likely disconnected, or the record has no phone in phone_field_slug. Check the session.
• send_webhook — Blocked host (private/local URL) or HTTP <status> (your endpoint returned non-2xx). See Webhooks.
• update_field / update_status — "No target record slug resolved" means the message trigger's chat isn't linked to a record (same cause as the activate 400).

Fix the cause, then POST /workflow/:slug/retry/:executionId (failed runs only).

Scheduled reminder never sends

• Confirm the workflow is active and its cron_expression / timezone are set (activation registers the repeatable job; pausing removes it).
• The reminder scans records inside the relative-date window; a 0 scanned run usually means the wrong object, an empty table, or the date window excluded every record. Each occurrence is de-duped, so a record is reminded once per occurrence.

A message fires the workflow twice

Message events are de-duped by message slug and per-chat (first_message has a 30-day once-per-chat guard). If you still see doubles, a provider is retrying the webhook with a different slug — make the action idempotent.

Still stuck? See the platform-wide Error reference.