facebook/react · error · Error

startTransition cannot be called during server rendering.

Error message

startTransition cannot be called during server rendering.

What it means

In Fizz, useTransition returns [false, unsupportedStartTransition]: transitions schedule updates, which is meaningless during the single pass of server rendering. Calling the returned startTransition function — or any code path that invokes it during SSR — throws immediately.

Source

Thrown at packages/react-server/src/ReactFizzHooks.js:642

  getSnapshot: () => T,
  getServerSnapshot?: () => T,
): T {
  if (getServerSnapshot === undefined) {
    throw new Error(
      'Missing getServerSnapshot, which is required for ' +
        'server-rendered content. Will revert to client rendering.',
    );
  }
  return getServerSnapshot();
}

function useDeferredValue<T>(value: T, initialValue?: T): T {
  resolveCurrentlyRenderingComponent();
  return initialValue !== undefined ? initialValue : value;
}

function unsupportedStartTransition() {
  throw new Error('startTransition cannot be called during server rendering.');
}

function useTransition(): [
  boolean,
  (callback: () => void, options?: StartTransitionOptions) => void,
] {
  resolveCurrentlyRenderingComponent();
  return [false, unsupportedStartTransition];
}

function useHostTransitionStatus(): TransitionStatus {
  resolveCurrentlyRenderingComponent();
  return NotPendingTransition;
}

function unsupportedSetOptimisticState() {
  throw new Error('Cannot update optimistic state while rendering.');
}

View on GitHub (pinned to eafeac097b)

Solutions

Move the startTransition call into an event handler (onClick, onSubmit) or effect so it runs only after hydration
Render the initial state directly on the server — transitions are a client-side interaction concern
Guard shared code so the transition path executes only inside browser event handlers

Example fix

// before
function Row({item, select}) {
  const [, start] = useTransition();
  start(() => select(item)); // called during render/SSR -> throws
}

// after
function Row({item, select}) {
  const [, start] = useTransition();
  return <li onClick={() => start(() => select(item))}>{item.name}</li>;
}

Defensive patterns

Strategy: validation

Validate before calling

// Guard shared code so transitions never run on the server.
const [, start] = useTransition();
const safeStart = callback => {
  if (typeof window === 'undefined') return; // SSR: skip
  start(callback);
};

Try / catch

try {
  start(() => select(item));
} catch (e) {
  if (String(e.message).includes('startTransition cannot be called during server rendering')) {
    // Move the call into an event handler; SSR renders initial state only.
  } else {
    throw e;
  }
}

Prevention

Call startTransition only inside event handlers and effects, never during render
Design server rendering as a pure single pass — render initial state directly
When sharing logic between client and server, gate transition code to browser-only paths

When it happens

Trigger: const [isPending, start] = useTransition(); start(() => select(item)) executed in a server-rendered component's body or a render helper; calling React.startTransition in code that runs during SSR; shared logic that kicks off transitions at render time.

Common situations: Components that start transitions during render instead of in handlers; React 18 to 19 upgrades where transition code newly runs during SSR; libraries invoking startTransition in initialization code that the server graph imports.

Related errors

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