Skip to main content

​
Troubleshooting: a Flow created from a template fails its first publish or test send

A Flow you created from one of the built-in templates — Appointment Booking, Order Tracking, Customer Satisfaction — shows up in the flow list like any other flow, yet the first publish or test send returns a validation error from WhatsApp and no screens would render for the recipient. Opening the flow in the editor and pressing Save clears the error. This page covers that failure: a flow whose screens never reached WhatsApp. If the Flow opens fine but completed submissions never land, work Troubleshoot WhatsApp Flow submissions instead; if the Flow fails mid-conversation, work Flow execution failures.
The recovery on this page is a tenant-owned control: the editor Save uploads your screens to your WABA’s flow. Nothing here requires a change on Orbit’s side.

​
Symptom

  • You create a Flow from a built-in template and give it a name. The flow appears under Messages → WhatsApp → Flows with the template’s screens previewable, so it looks finished.
  • Publish, or the dashboard’s test send, fails with a validation error from Meta. The error names none of your screens, because as far as WhatsApp is concerned the flow has none.
  • Opening the flow in the editor shows the full screen set, and pressing Save makes the next publish and test send succeed.
The cause is a flow that was created empty on the WABA side: the screens you saw lived only in your browser, and the flow’s JSON definition was never uploaded, so WhatsApp rejects publish and test send until it is. Flows created from a template before 24 October 2026 were always created this way. Since that date, creating from a template uploads the screens as part of creation; the failure remains for flows created earlier, and for the degraded path where attaching the screens at creation does not complete — the flow is still created in that case, and the dashboard tells you to review and save it from the editor.

​
Diagnosis: empty at WhatsApp vs a routing validation failure

Two different failures both surface as a Meta validation error on publish, so tell them apart before touching the JSON: The routing class is the one the Flows guide describes: fix the named screen and re-upload. The empty-flow class needs no JSON edits at all — the screens are already correct in the editor, they were just never uploaded.

​
Recovery: Save in the editor, then publish and test send

  1. Open the flow in the dashboard (Messages → WhatsApp → Flows, then the flow’s name). The editor hydrates the template’s screens.
  2. Press Save. The editor uploads the screens it shows, via POST /api/v1/whatsapp/flows/{flowId}/assets — the same assets endpoint the API exposes — so the flow on WhatsApp now matches what you saw.
  3. Run publish again, then the test send. Both succeed once the upload has landed.
There is nothing else to rebuild: the screens in the editor are the template’s original screens. Two creation paths never need this step: AI-generated flows upload their screens at creation, and template-created flows have done the same since 24 October 2026.

​
What not to do

  • Do not recreate the flow from scratch. The existing flow is fine once its screens are uploaded; a new flow mints a new Meta flow id and strands any send, flow_token, or webhook filter that references the old one.
  • Do not re-submit or re-pick the template. The template already contributed its screens to the editor; picking it again uploads nothing.
  • Do not edit the screens looking for a routing error when the editor shows a complete template and the errors name no screen. That is the empty-flow class; Save is the whole fix.
  • Do not retry publish or test send in a loop before saving. The validation error is deterministic until the screens upload; retries only burn the WABA’s Meta call budget — see the 502 META_API_ERROR page for budget behavior.

​
Escalation payload

If a Save in the editor does not clear the error, email whatsapp-support@devotel.io with these four items so we can trace the flow against Meta without a back-and-forth:
  1. The flow id (Meta’s id, or the id in the dashboard URL).
  2. The WABA id the flow was created on.
  3. The Meta error body — the validation_errors list from the failed publish or test send, verbatim.
  4. The request id from the failing response’s headers.

​
See also