facebook/react · error · Error

Server Functions cannot be called during initial render. Thi

Error message

Server Functions cannot be called during initial render. This would create a fetch waterfall. Try to use a Server Component to pass data to Client Components instead.

What it means

react-server-dom-esm's Node client (used to consume Flight payloads where no callback transport is wired) creates Server References whose callServer always throws (noServerCall). This is deliberate: calling a Server Function during initial render would serialize into an extra request per component — a fetch waterfall — so React blocks it and points you at Server Components for passing data down instead.

Source

Thrown at packages/react-server-dom-esm/src/client/ReactFlightDOMClientNode.js:35

import type {Readable} from 'stream';

import {
  createResponse,
  createStreamState,
  getRoot,
  reportGlobalError,
  processStringChunk,
  processBinaryChunk,
  close,
} from 'react-client/src/ReactFlightClient';

import {createServerReference as createServerReferenceImpl} from 'react-client/src/ReactFlightReplyClient';

export {registerServerReference} from 'react-client/src/ReactFlightReplyClient';

function noServerCall() {
  throw new Error(
    'Server Functions cannot be called during initial render. ' +
      'This would create a fetch waterfall. Try to use a Server Component ' +
      'to pass data to Client Components instead.',
  );
}

export function createServerReference<A: Iterable<any>, T>(
  id: any,
  callServer: any,
): (...A) => Promise<T> {
  return createServerReferenceImpl(id, noServerCall);
}

type EncodeFormActionCallback = <A>(
  id: any,
  args: Promise<A>,
) => ReactCustomFormAction;

View on GitHub (pinned to eafeac097b)

Solutions

  1. Move the call into an event handler or useEffect so it runs after render
  2. Fetch the data in a Server Component and pass it down as props instead
  3. If the work must happen during server-side rendering, run it in the react-server layer and stream the result into the payload

Example fix

// before — Server Function invoked during render
'use client';
export default function Stats() {
  const [stats, setStats] = useState(null);
  getStats().then(setStats); // throws: fetch waterfall
  return <pre>{JSON.stringify(stats)}</pre>;
}

// after — data comes from a Server Component
// StatsPage.server.js: const stats = await getStats(); return <Stats stats={stats}/>;
'use client';
export default function Stats({stats}) {
  return <pre>{JSON.stringify(stats)}</pre>;
}
Defensive patterns

Strategy: type-guard

Validate before calling

const SERVER_REFERENCE = Symbol.for('react.server.reference');
export function assertNotServerReferenceCall(fn, phase) {
  if (phase === 'render' && typeof fn === 'function' && fn.$$typeof === SERVER_REFERENCE) {
    throw new Error('Refusing to call a Server Function during render');
  }
}

Type guard

const SERVER_REFERENCE = Symbol.for('react.server.reference');
export function isServerReference(fn) {
  return typeof fn === 'function' && fn.$$typeof === SERVER_REFERENCE;
}
// in component bodies: if (isServerReference(fn)) do not invoke — only from handlers/effects

Try / catch

try {
  const root = createFromNodeStream(stream, rootPath, baseURL);
} catch (e) {
  if (/fetch waterfall/.test(e.message)) {
    // a component called a server function during render — move the call to an event handler
  }
  throw e;
}

Prevention

When it happens

Trigger: Any invocation of a Server Function reference during render in this client: calling it in a component body, in a layout, during SSR of the Flight payload, or otherwise outside an event handler — createServerReference deliberately drops its callServer argument and installs noServerCall.

Common situations: Porting data-fetching components to RSC and calling passed-down actions in render; SSR of client components that invoke actions at render time; tests that render and immediately call actions.

Related errors

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