facebook/react · error · Error

The React Server Writer cannot be used outside a react-serve

Error message

The React Server Writer cannot be used outside a react-server environment. You must configure Node.js using the `--conditions react-server` flag.

What it means

npm/server.js of react-server-dom-unbundled is what Node loads when the server entry is resolved WITHOUT the react-server export condition. The Flight server writer depends on the react-server build of react for correct semantics, so instead of silently using the wrong react it throws at import time with the required Node flag.

Source

Thrown at packages/react-server-dom-unbundled/npm/server.js:3

'use strict';

throw new Error(
  'The React Server Writer cannot be used outside a react-server environment. ' +
    'You must configure Node.js using the `--conditions react-server` flag.'
);

View on GitHub (pinned to eafeac097b)

Solutions

Run Node with the flag: `node --conditions react-server server.js`.
Configure test runners: jest `customExportConditions: ['node', 'react-server']`, vitest `resolve.conditions` including 'react-server'.
Put the flag in NODE_OPTIONS if child processes import the server entry.
Confirm resolution with `node --conditions react-server -e "console.log(require.resolve('react-server-dom-unbundled/server'))"`.

Example fix

# before
node server.js

# after
node --conditions react-server server.js

Defensive patterns

Strategy: validation

Validate before calling

if (!process.execArgv.some(a => a.includes('react-server'))) {
  throw new Error('Run with: node --conditions react-server');
}

Prevention

Add --conditions react-server to every script that imports the server entry.
Propagate NODE_OPTIONS to spawned workers.
Document the flag in the repo README so operators copy correct start commands.

When it happens

Trigger: `import ... from 'react-server-dom-unbundled/server'` executed in a Node process without `--conditions react-server` (plain `node script.js`, default test-runner resolution).

Common situations: Running an RSC server or unit tests without the condition flag; NODE_OPTIONS not propagated to child processes; framework upgrades that dropped the flag from start scripts.

Related errors

AI-assisted analysis of facebook/react@eafeac097b (2026-08-21). Data as JSON: /api/errors/70a7c056cea6c55b. Report an issue: GitHub.