Uh oh!
There was an error while loading. Please reload this page.
[docs] Add "Step executed multiple times" error page - #2310
Merged
Conversation
Document duplicate step_started events caused by function crashes (timeouts, OOMs, network issues) for both v4 and v5 docs. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
🦋 Changeset detectedLatest commit: 6b93afc The changes in this PR will be included in the next version bump. This PR includes changesets to release 0 packagesWhen changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
TooTallNate
approved these changes
Jun 10, 2026
TooTallNate
left a comment
Member
There was a problem hiding this comment.
Approve — accurate, well-scoped troubleshooting page
Clean docs-only addition. The new "Step executed multiple times" page correctly explains a real behavior: when a step's function invocation hard-crashes (timeout / OOM / network) after the step_started event is recorded but before it can write a terminal step_completed/step_failed event, the queue redelivers the message and executeStep runs again, producing another step_started for the same correlationId. The result is N step_started events with no visible error — exactly what the page describes.
I traced this through packages/core/src/runtime/step-executor.ts:143 (step_started is created at the top of executeStep, terminal events are written only after the function returns). The "no error visible in the Observability UI" framing is accurate for the SIGKILL paths (OOM/timeout) where the runtime never gets to call dehydrateStepError.
What I checked
- Content parity: v4 and v5 pages are byte-identical, which is correct here — the behavior is the same on both channels.
- Link targets resolve (both v4 and v5):
prerequisites: /docs/foundations/workflows-and-steps✓related: /docs/observability→observability/index.mdx✓related: /docs/foundations/errors-and-retries✓
- Two observability links are intentional and distinct: line 13 links the workflow SDK's own
/docs/observability("Observability UI"); line 18 links Vercel's product docshttps://vercel.com/docs/observabilityfor the Function Invocation Peak Memory metric (a Vercel platform feature, not an SDK feature). Both correct. - Index card placed next to
step-not-registered— a sensible thematic grouping (the list isn't strictly alphabetical anyway; newer entries are appended). - Changeset is the empty
---\n---form, correct for docs-only changes (docs/is in changesetignore). - CI:
mergeable: MERGEABLE; test matrix is correctly skipped by path filters;BLOCKEDis just the required E2E check sitting in skipped/pending, normal for docs PRs. Branch is based on the recentVersion Packages (beta)commit, not stale.
One non-blocking observation
Every other page in errors/ uses the kebab-case error code as its title (step-not-registered, corrupted-event-log, replay-divergence, …) and matching card titles, because each corresponds to an actual runtime error name. This page uses prose (Step executed multiple times) in both the frontmatter title and the index card. That's defensible — there is no StepExecutedMultipleTimesError; this is a behavioral troubleshooting topic rather than a named error — so the prose title is arguably more honest. Just flagging the convention divergence in case you'd prefer consistency (e.g. a kebab title with a friendly summary). Not a blocker either way.
LGTM.
Uh oh!
There was an error while loading. Please reload this page.
github-actionsBot
added a commit
that referenced
this pull request
Jun 10, 2026
Signed-off-by: Peter Wielander <mittgfu@gmail.com>
Contributor
Backport PR opened against |
pranaygp added a commit
that referenced
this pull request
Jun 11, 2026
…-attributes-client * origin/main: (32 commits) feat(core): add optional namespace for queue topic prefix (#2305) [web-shared] Show precise durations in the new trace viewer (#2335) Validate unique workflow step IDs at build time (#2018) Move run attributes into their own detail card (#2327) [core] Forward-port stream reconnect to getReadable level (#2318) [docs] Add "Step executed multiple times" error page (#2310) Fix flickering on the detail panel when navigating the trace viewer (#2325) Version Packages (beta) (#2254) Patch vulnerable package dependencies (#2301) Deprecate DurableAgent and update it with WorkflowAgent in v5 docs (#2285) [codex] Fix partial world-local exclusive writes (#2296) [world-vercel] Validate ref resolve responses before use (#2035) fix: bump devalue to 5.8.1 (#2292) Handle lazy stream key request failures (#2257) fix(docs): declare Nitro auto-import globals for code samples (#2290) [core] Preserve event-log order in hook-vs-sleep replay races (#2171) (#2185) docs: add nitro changelog (#2232) fix(next): always apply turbopack content condition regardless of builder mode (#2253) Update @vercel/queue from 0.2.1 to 0.3.0 (#2255) [nest] Use AST-based CommonJS import rewriting (#2080) ... # Conflicts: # packages/world-local/src/storage/events-storage.ts
VaguelySerious added a commit
that referenced
this pull request
Jun 11, 2026
pranaygp added a commit
that referenced
this pull request
Jun 11, 2026
…hook-ready * origin-https/main: (119 commits) fix: settle aborted parallel steps before completing abortParallelWorkflow (#2244) Add native v4 workflow attribute events (#2226) Version Packages (beta) (#2326) [ci] Fix flaky windows unit tests (#2359) Capture Vercel runtime logs when e2e Vercel Prod lanes fail (#2356) Fix e2e failure reporting under vitest 4 and preserve fetch error causes (#2355) [core] Fix process crash from rejected waitUntil promises (#2336) [core] Remove duplicate `waitUntil` for suspension handler async operations (#2345) Prevent local tests from hanging (#2338) feat(core): add optional namespace for queue topic prefix (#2305) [web-shared] Show precise durations in the new trace viewer (#2335) Validate unique workflow step IDs at build time (#2018) Move run attributes into their own detail card (#2327) [core] Forward-port stream reconnect to getReadable level (#2318) [docs] Add "Step executed multiple times" error page (#2310) Fix flickering on the detail panel when navigating the trace viewer (#2325) Version Packages (beta) (#2254) Patch vulnerable package dependencies (#2301) Deprecate DurableAgent and update it with WorkflowAgent in v5 docs (#2285) [codex] Fix partial world-local exclusive writes (#2296) ... # Conflicts: # packages/core/src/runtime.ts # packages/core/src/runtime/suspension-handler.ts
pranaygp added a commit
that referenced
this pull request
Jun 11, 2026
…docs-run-idempotency * origin-https/main: (115 commits) [core] V2: unify wait+step queue dispatch in suspension processing (#1925) fix(world-local,world-postgres): make duplicate hook_created idempotent (#2295) docs(observability): remove MVP implementation detail bullet (#2367) fix: settle aborted parallel steps before completing abortParallelWorkflow (#2244) Add native v4 workflow attribute events (#2226) Version Packages (beta) (#2326) [ci] Fix flaky windows unit tests (#2359) Capture Vercel runtime logs when e2e Vercel Prod lanes fail (#2356) Fix e2e failure reporting under vitest 4 and preserve fetch error causes (#2355) [core] Fix process crash from rejected waitUntil promises (#2336) [core] Remove duplicate `waitUntil` for suspension handler async operations (#2345) Prevent local tests from hanging (#2338) feat(core): add optional namespace for queue topic prefix (#2305) [web-shared] Show precise durations in the new trace viewer (#2335) Validate unique workflow step IDs at build time (#2018) Move run attributes into their own detail card (#2327) [core] Forward-port stream reconnect to getReadable level (#2318) [docs] Add "Step executed multiple times" error page (#2310) Fix flickering on the detail panel when navigating the trace viewer (#2325) Version Packages (beta) (#2254) ... # Conflicts: # docs/content/docs/v4/cookbook/advanced/child-workflows.mdx # docs/content/docs/v5/cookbook/advanced/child-workflows.mdx # docs/content/docs/v5/cookbook/agent-patterns/durable-agent.mdx
pranaygp added a commit
that referenced
this pull request
Jun 11, 2026
* origin/main: [core] V2: unify wait+step queue dispatch in suspension processing (#1925) fix(world-local,world-postgres): make duplicate hook_created idempotent (#2295) docs(observability): remove MVP implementation detail bullet (#2367) fix: settle aborted parallel steps before completing abortParallelWorkflow (#2244) Add native v4 workflow attribute events (#2226) Version Packages (beta) (#2326) [ci] Fix flaky windows unit tests (#2359) Capture Vercel runtime logs when e2e Vercel Prod lanes fail (#2356) Fix e2e failure reporting under vitest 4 and preserve fetch error causes (#2355) [core] Fix process crash from rejected waitUntil promises (#2336) [core] Remove duplicate `waitUntil` for suspension handler async operations (#2345) Prevent local tests from hanging (#2338) feat(core): add optional namespace for queue topic prefix (#2305) [web-shared] Show precise durations in the new trace viewer (#2335) Validate unique workflow step IDs at build time (#2018) Move run attributes into their own detail card (#2327) [core] Forward-port stream reconnect to getReadable level (#2318) [docs] Add "Step executed multiple times" error page (#2310) Fix flickering on the detail panel when navigating the trace viewer (#2325)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Preview link
Adds a new troubleshooting page, "Step executed multiple times", to both the v4 and v5 docs. It explains why a workflow run might show multiple
step_startedevents for the same step