Do not assign null to plural linked fields; assign an empty

Error message

Do not assign null to plural linked fields; assign an empty array instead.

What it means

This error is thrown by Relay's updatable proxy layer when a developer assigns null to a plural (list) linked field via an updater's `set` function. Relay requires plural linked fields to always hold an array of records; null is not a valid value for them because it cannot be represented as a list of linked records in the store. Assigning `[]` clears the list instead.

Source

Thrown at packages/relay-runtime/mutations/createUpdatableProxy.js:211

      default:
        selection.kind as empty;
        throw new Error(
          'Encountered an unexpected ReaderSelection variant in RelayRecordSourceProxy. This indicates a bug in Relay.',
        );
    }
  }
}

function createSetterForPluralLinkedField(
  selection: ReaderLinkedField,
  variables: Variables,
  updatableProxyRootRecord: RecordProxy,
  recordSourceProxy: RecordSourceProxy,
) {
  return function set(newValue: ReadonlyArray<{__id: string, ...}>) {
    const newVariables = getArgumentValues(selection.args ?? [], variables);
    if (newValue == null) {
      throw new Error(
        'Do not assign null to plural linked fields; assign an empty array instead.',
      );
    } else {
      const recordProxies = newValue.map((item): ?RecordProxy => {
        if (item == null) {
          throw new Error(
            'When assigning an array of items, none of the items should be null or undefined.',
          );
        }
        const {__id} = item;
        if (__id == null) {
          throw new Error(
            'The __id field must be present on each item passed to the setter. This indicates a bug in Relay.',
          );
        }
        const newValueRecord = recordSourceProxy.get(__id);
        if (newValueRecord == null) {
          throw new Error(

View on GitHub (pinned to 668b1b85e0)

Solutions

Replace `field.set(null)` with `field.set([])` to clear the list
If the source value may be null, coerce it: `field.set(value ?? [])`
If the field is truly single-valued, verify the GraphQL schema — the field is plural, so a non-array assignment is invalid

Example fix

// before
updatable.viewer.friends.set(null);
// after
updatable.viewer.friends.set([]);

Defensive patterns

Strategy: validation

Validate before calling

function canSetPlural(value) {
  return Array.isArray(value);
}
if (!canSetPlural(next)) throw new TypeError('Expected an array; use [] instead of null for plural linked fields');

Type guard

function isNonEmptyAssignable<T>(v: ReadonlyArray<T> | null | undefined): v is ReadonlyArray<T> {
  return v != null;
}

Try / catch

try {
  field.set(next);
} catch (e) {
  if (e.message.includes('plural linked fields')) field.set(next ?? []);
  else throw e;
}

Prevention

Never assign null to plural linked fields; use [] to clear
Coerce nullable sources with ?? [] before set()
Type the setter input as ReadonlyArray<T>, not T | null
Add unit tests for clearing lists via updaters

When it happens

Trigger: Inside an updater or optimisticUpdater of a mutation/subscription, calling `updatableField.set(null)` where the GraphQL field is a plural linked field (a list of objects with ids).

Common situations: Clearing a list of items after a delete mutation; copying a nullable query result variable into a plural field; copying a value from a response that returned null for a list.

Related errors

AI-assisted analysis of facebook/relay@668b1b85e0 (2026-09-02). Data as JSON: /api/errors/d305c26436ef4ed9. Report an issue: GitHub.