Flight booking app fails with v5 beta release with "received text-delta for missing text part with ID 0"

[VaguelySerious]

When I ran Flight Booking App from vercel/workflow-examples against workflow SDK 5.0.0-beta.15, after some turns, I sometimes get an error message saying:

Received text-delta for missing text part with ID "0". Ensure a "text-start" chunk is sent before any "text-delta" chunks.

E.g. on wrun_01KV5JQDXEKZZB6GEHPCHFKYGP.

I'm having trouble reproducing this consistently

[jlovelace-bg]

We hit this same error consistently in production (AI SDK UI message stream over a resumable, multi-worker setup) and tracked down a reproducible root cause that may help.

Root cause we found

The error fires when the same durable run's doStreamStep executes more than once and both executions write UI chunks to the same shared stream. In our workflow journal the final model step showed attempt = 2, i.e. the step was redelivered/ran concurrently rather than once. With two executions feeding one stream, the chunks interleave:

• a finish-step from execution A lands in the middle of execution B's text part, and/or
• the text-start for part "0" is only delivered once, while a later text-delta / text-end for "0" still arrives.

By the time processUIMessageStream sees that text-delta, it no longer has an open part "0" → Received text-delta for missing text part with ID "0".

A key detail that makes this easy to trip even without full concurrency: the SDK resets its active text/reasoning part maps on every finish-step, and multi-step turns reuse the same part id ("0") in each step. So a single dropped or duplicated text-start across a step boundary is enough to orphan the rest of that step's text.

We believe the duplicate execution itself is the same family as the concurrent-worker world-postgres races in #2331 and #2039 (multiple workers picking up the same pending step, especially around scale-up / pod rollover). The "missing text part" error is the client-visible symptom of that server-side duplication landing on a shared stream.

Mitigation (client side)

Since the content is still flowing and only the part framing is damaged, we stopped hard-failing the turn by inserting a transform between the transport stream and the SDK that mirrors the SDK's part-lifetime state machine:

• track which part ids are open / ended per step;
• reset that tracking on start and on every finish-step (so a part id legitimately reused in a later step isn't mistaken for a duplicate, and a dropped start for it gets synthesized);
• synthesize a missing *-start when an orphaned *-delta / *-end arrives;
• drop a re-delivered *-start / *-delta / *-end for a part already open/ended in the same step (reconnect/replay overlap).

Well-formed streams pass through untouched; the worst case degrades to "the visible text begins slightly into the step" or "a duplicated tail is dropped" instead of a dead turn.

Sketch of the core (text parts; reasoning is symmetric):

let open = new Set<string>();
let ended = new Set<string>();
const reset = () => { open = new Set(); ended = new Set(); };

for await (const chunk of chunks) {
  switch (chunk.type) {
    case "start":
    case "finish-step":
      reset();
      break;
    case "text-start":
      if (open.has(chunk.id) || ended.has(chunk.id)) continue; // drop duplicate
      open.add(chunk.id);
      break;
    case "text-delta":
      if (ended.has(chunk.id)) continue;                       // drop post-end replay
      if (!open.has(chunk.id)) { open.add(chunk.id); yield { type: "text-start", id: chunk.id }; }
      break;
    case "text-end":
      if (ended.has(chunk.id)) continue;
      if (!open.has(chunk.id)) yield { type: "text-start", id: chunk.id };
      open.delete(chunk.id); ended.add(chunk.id);
      break;
  }
  yield chunk;
}