Repository navigation
docs: require system environment variables when deploying to Vercel - #4166
Merged
Merged
Conversation
|
Contributor
VaguelySerious
approved these changes
Sep 14, 2026
VaguelySerious
left a comment
VaguelySerious
left a comment
Member
There was a problem hiding this comment.
Should this also throw when detecting that we're running in vercel world?
Contributor
Sim WorldSimulated world deterministic testing for races. Traces 🟠 world-sim scenario book — 1 fail of 41 total
Full trace: |
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Moderate documentation accuracy issues and the required preview URLs remain unresolved.
Get a fresh assessment by requesting another Copilot review.
Pull request overview
This docs-only PR documents the Vercel system-environment-variable prerequisite for correctly selecting the Vercel World.
Changes:
- Adds v4/v5 setup and troubleshooting guidance for
VERCEL_DEPLOYMENT_ID. - Adds Vercel deployment prerequisite callouts.
- Documents missing-variable behavior in world configuration.
File summaries
| File | Reviewed change |
|---|---|
docs/content/worlds/v5/vercel.mdx |
Adds setup guidance and diagnostics. |
docs/content/worlds/v4/vercel.mdx |
Adds v4-compatible prerequisite guidance. |
docs/content/docs/v5/deploying.mdx |
Adds deployment prerequisite callout. |
docs/content/docs/v5/configuration/worlds.mdx |
Documents missing deployment-ID behavior. |
docs/content/docs/v4/deploying.mdx |
Adds v4 deployment prerequisite callout. |
Review details
Suppressed comments (5)
docs/content/docs/v4/deploying.mdx:61
- The callout repeats the same blanket claim, but
WORKFLOW_LOCAL_DATA_DIR=/tmpis a supported writable exception on Vercel (packages/world-local/src/build-target-mismatch.ts:82-83). Please qualify the failure to the default/non-writable data directory and note that/tmpis ephemeral rather than durable.
falls back to the Local World and every run fails on the read-only
filesystem. See
[System environment variables](/worlds/vercel#system-environment-variables).
docs/content/docs/v5/deploying.mdx:62
- The PR description's
Docs Previewtable still contains relative route fragments and says the links will be filled in later. Before approval, replace them with directworkflow-docspreview URLs from thevercel[bot]comment for the changed v4/v5 pages, as required for docs changes.
[System environment variables](/worlds/vercel#system-environment-variables).
docs/content/docs/v5/deploying.mdx:62
- The callout repeats the same blanket claim, but
WORKFLOW_LOCAL_DATA_DIR=/tmpis a supported writable exception on Vercel (packages/world-local/src/build-target-mismatch.ts:82-83). Please qualify the failure to the default/non-writable data directory and note that/tmpis ephemeral rather than durable.
falls back to the Local World and every run fails on the read-only
filesystem. See
[System environment variables](/worlds/vercel#system-environment-variables).
docs/content/worlds/v4/vercel.mdx:52
- This is too absolute:
WORKFLOW_LOCAL_DATA_DIRcan point at/tmp, and the Local World explicitly treats/tmpas writable on Vercel (packages/world-local/src/build-target-mismatch.ts:82-83). With that configuration the first write is not guaranteed to fail, although the state is ephemeral, so qualify this to the default/non-writable data directory.
workflow state on the filesystem. A deployment's filesystem is read-only, so
every run fails before its first step, and no runs appear in the Vercel
dashboard because none were ever created in the Vercel World.
docs/content/worlds/v5/vercel.mdx:56
- The v5 runtime now throws
UnwritableDataDirError, whose message explicitly identifies the local filesystem World, Vercel's read-only filesystem, and the Vercel-World fix (packages/world-local/src/build-target-mismatch.ts:25-33). Saying that nothing announces the wrong World is therefore misleading; distinguish the missing startup warning from the diagnostic write error.
Nothing in the deployment announces the wrong World, so the failure is easy to mistake for a bug in the SDK:
- Files reviewed: 5/5 changed files
- Comments generated: 2
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+49
to
+50
| output and the runtime selects the [Local World](/worlds/local), which stores | ||
| workflow state on the filesystem. A deployment's filesystem is read-only, so |
Member
Author
There was a problem hiding this comment.
AI: Agreed. Updated the v4 warning in 158b0fb to say that the runtime selects Local World unless WORKFLOW_TARGET_WORLD is set, and scoped the filesystem failure to that default selection. This keeps it consistent with the note below about explicitly selecting Vercel World still requiring VERCEL_DEPLOYMENT_ID.
Comment on lines
+49
to
+50
| output and the runtime selects the [Local World](/worlds/local), which stores | ||
| workflow state on the filesystem. A deployment's filesystem is read-only, so |
Member
Author
There was a problem hiding this comment.
AI: Agreed. Updated the v5 warning in 158b0fb to qualify Local World selection and its filesystem failure as the default when no WORKFLOW_TARGET_WORLD override is set. Also applied that qualifier to the diagnostic symptoms, so they do not imply that an explicit Vercel World override selects Local World. Lint and MDX compilation passed; the link checker could not run because the installed Bun executable failed to launch.
karthikscale3
approved these changes
Sep 14, 2026
Workflow recognizes a Vercel deployment by VERCEL_DEPLOYMENT_ID, which Vercel only exposes when "Enable access to System Environment Variables" is selected in the project's Environment Variables settings. A project that cleared that checkbox looks like a non-Vercel environment to the SDK: the build emits local output and the runtime selects the Local World, whose writes then fail on the deployment's read-only filesystem. Nothing announces the wrong World, because the "local world inside a Vercel deployment" warning keys off the same missing variable. Document the setting as a deployment prerequisite on both deploying pages and both Vercel World pages, add a diagnosis section covering the symptoms and why WORKFLOW_TARGET_WORLD=vercel is not a workaround, and note it alongside World selection in the v5 configuration reference. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-Authored-By: Nathan Rajlich <71256+TooTallNate@users.noreply.github.com>
Co-Authored-By: Nathan Rajlich <71256+TooTallNate@users.noreply.github.com>
TooTallNate
force-pushed
the
docs-system-env-vars
branch
from
September 16, 2026 20:26
b2857aa to
158b0fb
Compare
github-actions Bot
added a commit
that referenced
this pull request
Sep 16, 2026
…4166) * docs: require system environment variables when deploying to Vercel Workflow recognizes a Vercel deployment by VERCEL_DEPLOYMENT_ID, which Vercel only exposes when "Enable access to System Environment Variables" is selected in the project's Environment Variables settings. A project that cleared that checkbox looks like a non-Vercel environment to the SDK: the build emits local output and the runtime selects the Local World, whose writes then fail on the deployment's read-only filesystem. Nothing announces the wrong World, because the "local world inside a Vercel deployment" warning keys off the same missing variable. Document the setting as a deployment prerequisite on both deploying pages and both Vercel World pages, add a diagnosis section covering the symptoms and why WORKFLOW_TARGET_WORLD=vercel is not a workaround, and note it alongside World selection in the v5 configuration reference. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-Authored-By: Nathan Rajlich <71256+TooTallNate@users.noreply.github.com> * docs: qualify default World selection warnings Co-Authored-By: Nathan Rajlich <71256+TooTallNate@users.noreply.github.com> --------- Co-authored-by: vercel[bot] <35613825+vercel[bot]@users.noreply.github.com> Co-authored-by: Nathan Rajlich <71256+TooTallNate@users.noreply.github.com> Signed-off-by: Nathan Rajlich <n@n8.io>
Contributor
|
Backport PR opened against |
This branch was successfully deployed
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 free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Why
A customer's Vercel deployment silently ran on the Local World and every run failed. The cause was that their project had Enable access to System Environment Variables turned off, so Vercel never set
VERCEL_DEPLOYMENT_ID— the single signal Workflow uses to recognize a deployment (resolveWorkflowTargetWorldinpackages/utils/src/world-target.ts).Nothing in the docs said that setting was a prerequisite, and nothing in the deployment points at it either:
VERCEL_DEPLOYMENT_IDtoo (packages/next/src/index.ts,packages/astro/src/plugin.ts,packages/sveltekit/src/index.ts), so it emits local output instead of the queue-triggered flow handler.warnIfRunningInVercelDeploymentwarning that would name the mistake keys off the same missing variable, so it never fires.WORKFLOW_TARGET_WORLD=vercelis not a workaround: the Vercel World needs the deployment ID itself and fails withmissingDeploymentIdMessage.What changed
Docs only — no code, no changeset (
pnpm changeset status --since=mainreports none needed).worlds/{v4,v5}/vercel.mdx— new## System environment variablessection: what the variable is for, the four dashboard steps to enable it, and the consequence of leaving it off. v5 also gets a### Diagnosing a missing deployment IDsubsection covering the symptoms (EROFSon the Local World data directory, no runs in the dashboard, no warning) and whyWORKFLOW_TARGET_WORLD=verceldoes not help. The v4 text is trimmed to behavior that exists on 4.x, which has noUnwritableDataDirErroror in-deployment warning.docs/{v4,v5}/deploying.mdx— a prerequisite callout in "Deploying to Vercel", next to the existing Fluid compute callout, linking to the new section.docs/v5/configuration/worlds.mdx— noted underWORKFLOW_TARGET_WORLD, right after theWORKFLOW_TARGET_WORLD=localcase, since it is the other way a deployment ends up on the Local World (and the one that produces no warning). Also qualified the "platform-provided values" paragraph.docs/content/docs/v4/has noconfiguration/section, so the v4 pages link to/worlds/vercel#system-environment-variablesrather than the configuration reference.Verification
pnpm --filter docs lint:links(docs/scripts/lint.ts) passes:0 errored file, 0 errors.Docs Preview
🤖 Generated with Claude Code