Flow monitoring & troubleshooting

Where to watch flow runs, how to read a failed run down to the node that broke, and the five failures you will actually meet — symptom, cause, and the fix you can do yourself.

What to watch#

• Run Monitor (Integration → Runs): every flow execution in one list — flow name and version, how it was triggered (schedule / event / manual), status (running, success, failed, retrying), duration and items processed. Filter by status to see only the failures.
• Run detail: click a run to see it node by node — each step’s input snapshot, output snapshot and, for the failed step, the exact error message. Always start here: the failing node and its input usually point straight at the cause.
• Logs & Dead letters (Integration → Logs): items that failed permanently land in the dead-letter queue with the flow, the node and the error. After you fix the cause, replay a dead letter to process that item again — or discard it if it is no longer wanted.
• Connection health: a run that fails at its first node with an auth error is a connection problem, not a flow problem — the connection’s own Test button reproduces it in seconds.

The five failures below cover almost everything you will see. For each: what it looks like, why it happens, and the fix — all things you can do from the UI, no engineering ticket needed.

1. Credentials expired or invalid#

• Symptom: runs fail at the first node with 401 / auth failed; the connection Test fails the same way. It often starts suddenly after working for weeks.
• Cause: the other platform expired or rotated the credential — tokens have lifetimes (e.g. Wish access tokens 30 days; some OAuth user tokens only hours), and secrets change when someone regenerates them in the platform admin.
• Fix: (1) get a fresh credential from the platform (the connector directory entry lists exactly where); (2) open the connection, paste the new value, save; (3) run the connection Test until it passes; (4) replay the dead letters the outage produced.

2. Mapping missing or wrong type#

• Symptom: runs fail at a middle node with errors like “field X is required”, “unmapped SKU”, or a value rejected as the wrong type (text where a number is expected, a date in the wrong format). New orders with new SKUs are the classic trigger.
• Cause: a source field the mapping expects was empty or absent on that document, two systems disagree on a field’s type, or a channel SKU has never been paired with an OMS product.
• Fix: (1) open the failed run and read which node and field failed; (2) for unmapped SKUs, pair them in Product Mapping’s pending list; (3) for a missing / mistyped field, open the flow (or connection) mapping, map the right source field or add a default / conversion for that field; (4) dry-run to confirm, publish if you edited the flow, then replay the dead letter.

3. The other platform is rate-limiting you#

• Symptom: runs show status “retrying”, or fail with 429 / “too many requests”. Bursts make it worse — e.g. right after a big manual pull or at the top of the hour when many flows fire together.
• Cause: every platform caps how many API calls an account may make per minute/hour. The connector already retries with backoff — that is what “retrying” means — but a sustained burst can still exhaust the budget.
• Fix: (1) do nothing for occasional “retrying” — it usually succeeds on its own; (2) if it repeats, lower the pull frequency on the connection / flow schedule; (3) stagger schedules so several flows do not hit the same platform at the same minute; (4) avoid repeated manual pulls while a backlog is retrying.

4. Webhook / callback failures#

• Symptom: data that should arrive by push never shows up — tracking numbers or fulfillment confirmations stay missing, or new-order notifications stop — while manual pulls still work. Logs show webhook delivery errors.
• Cause: the sending platform could not deliver to Docklify (temporary network issue), the subscription was dropped when credentials changed, or the connection was disabled and re-enabled without the callback being re-registered.
• Fix: (1) check Integration → Logs for the webhook errors and their times — a short burst that already stopped needs no action; (2) test the connection; a successful test re-validates the callback registration on most platforms; (3) if pushes are still missing, disable and re-enable the connection to force a fresh subscription; (4) pull manually once to backfill what was missed, then watch the next real event arrive.

5. Data format problems#

• Symptom: individual documents fail while others on the same connection succeed — a specific order is rejected for an invalid address, a phone number in the wrong shape, a postcode that does not parse, or a weight with the unit inside the number.
• Cause: the data itself, as it exists on the source platform or in the source document, does not meet the receiving side’s format rules. The flow and the credentials are fine — the document is not.
• Fix: (1) open the failed run and read which document and which field was rejected — the error names it; (2) fix the data at the source where you can (correct the address / phone on the order or in the platform); (3) if the same quirk keeps coming from that platform, handle it once in the mapping instead: add a default, trim or conversion for that field; (4) replay the dead letter for the fixed document.