POST /.well-known/workflow/v1/flow 500s with MessageNotAvailableError

Start at the generated POST /.well-known/workflow/v1/flow callback route and compare the @vercel/queue@0.5.1 behavior with 0.6.0, especially the polling client's handling of MessageNotAvailableError. Verify whether 409 and 410 callbacks should return 200 without retrying, then confirm the Vercel World dependency path and add or run the relevant callback checks if available.

I've been seeing this issue for a while across workflows v4 and v5 betas. I have an alert on any 500s which this issue is triggering. I believe this in benign, but I'd like to both confirm this and if possible have the framework handle it correctly. It seems that @vercel/queue@0.6.0 handles this case differently so perhaps upgrading is the best fix?

Report from my agent:

We've been seeing bursts of 500s on the generated workflow callback route:

Queue callback error: Error [MessageNotAvailableError]: Message <id> not available for processing

Most /.well-known/workflow/v1/flow requests succeed. These 500s show up in short spikes when a lot of callbacks fire at once (high fan-out, sometimes alongside 504s from long-running steps). The stack stays in the queue callback, not in our "use workflow" / "use step" code, and the runs themselves usually keep going.

From what we can tell, VQS delivers a callback, the consumer tries to claim the message by id, and VQS returns 409 because the message isn't available (already leased or otherwise not claimable). @vercel/queue@0.5.1 logs that as Queue callback error and responds 500. The polling client already treats the same error as { ok: false, reason: "not_available" } rather than a failure.

We're on workflow@5.0.0-beta.51 / @workflow/world-vercel@5.0.0-beta.46, which resolve @vercel/queue@0.5.1. Latest published Workflow packages still seem to sit on 0.5.1.

@vercel/queue@0.6.0 looks like it may address this: 409 / MessageNotAvailableError (and 410 / already processed) are documented as skipped with a 200 instead of a 500, so they wouldn't retry a message that can't be claimed. We haven't verified that in production. If that's the intended behavior, it might be worth pulling 0.6.0 into the Vercel World path when you're ready — otherwise we're happy to hear if this 500 is expected or if we're holding something incorrectly.

Related, but not the same error text: #925 / #1012 (visibility extension) and #579 (MessageNotFoundError).