facebook/react · error · Error

Cannot assign to a client module from a server module.

Error message

Cannot assign to a client module from a server module.

What it means

The deep proxy around each named export of a client module implements a throwing `set` trap. Server code cannot mutate a client reference: the value lives in the browser bundle, and assignment on the server would be silently lost. Any write to a property of a client export therefore throws immediately.

Source

Thrown at packages/react-server-dom-unbundled/src/ReactFlightUnbundledReferences.js:204

        // This allows server components to render <ClientContext.Provider>
        // which will be serialized and executed on the client.
        return receiver;
      case 'then':
        throw new Error(
          `Cannot await or return from a thenable. ` +
            `You cannot await a client module from a server component.`,
        );
    }
    // eslint-disable-next-line react-internal/safe-string-coercion
    const expression = String(target.name) + '.' + String(name);
    throw new Error(
      `Cannot access ${expression} on the server. ` +
        'You cannot dot into a client module from a server component. ' +
        'You can only pass the imported name through.',
    );
  },
  set: function () {
    throw new Error('Cannot assign to a client module from a server module.');
  },
};

function getReference(target: Function, name: string | symbol): $FlowFixMe {
  switch (name) {
    // These names are read by the Flight runtime if you end up using the exports object.
    case '$$typeof':
      return target.$$typeof;
    case '$$id':
      return target.$$id;
    case '$$async':
      return target.$$async;
    case 'name':
      return target.name;
    // We need to special case this because createElement reads it if we pass this
    // reference.
    case 'defaultProps':
      return undefined;

View on GitHub (pinned to eafeac097b)

Solutions

1. Move the mutation into the client module itself (configure it where it runs, in the browser).
2. Pass configuration as props/arguments to the client component instead of mutating it from the server.
3. For test stubs, mock the module in the module graph (jest moduleNameMapper / vi.mock) rather than assigning to its exports.

Example fix

// before (server code)
import Button from './Button.client';
Button.defaultProps = { size: 'md' };

// after
<Button size="md" {...props} />

// Guard mutations before they happen
function assertNotClientReference(target) {
  if (target != null && target.$$typeof === Symbol.for('react.client.reference')) {
    throw new Error('Refusing to assign to a client reference');
  }
}
assertNotClientReference(Button);

When it happens

Trigger: In a server module: `clientExport.foo = value`, e.g. setting `Button.defaultProps`, monkey-patching a client utility, or `Object.assign(someClientExport, {...})` from server code.

Common situations: Configuring plugins/defaultProps on components that turned out to be client references; libraries that attach markers or cache onto imported functions; test setup files that stub exports of 'use client' modules while running in a server environment.

Related errors

• Cannot await or return from a thenable. You cannot await a c
• Cannot access ${expression} on the server. You cannot dot in
• Cannot read Symbol exports. Only named exports are supported
• Attempted to call ${String(name)}() from the server but ${St
• Attempted to call the default export of ${url} from the serv

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