{"record":{"id":"d305c26436ef4ed9","repo":"facebook/relay","slug":"do-not-assign-null-to-plural-linked-fields-assign","errorCode":null,"errorMessage":"Do not assign null to plural linked fields; assign an empty array instead.","messagePattern":"Do not assign null to plural linked fields; assign an empty array instead\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/relay-runtime/mutations/createUpdatableProxy.js","lineNumber":211,"sourceCode":"      default:\n        selection.kind as empty;\n        throw new Error(\n          'Encountered an unexpected ReaderSelection variant in RelayRecordSourceProxy. This indicates a bug in Relay.',\n        );\n    }\n  }\n}\n\nfunction createSetterForPluralLinkedField(\n  selection: ReaderLinkedField,\n  variables: Variables,\n  updatableProxyRootRecord: RecordProxy,\n  recordSourceProxy: RecordSourceProxy,\n) {\n  return function set(newValue: ReadonlyArray<{__id: string, ...}>) {\n    const newVariables = getArgumentValues(selection.args ?? [], variables);\n    if (newValue == null) {\n      throw new Error(\n        'Do not assign null to plural linked fields; assign an empty array instead.',\n      );\n    } else {\n      const recordProxies = newValue.map((item): ?RecordProxy => {\n        if (item == null) {\n          throw new Error(\n            'When assigning an array of items, none of the items should be null or undefined.',\n          );\n        }\n        const {__id} = item;\n        if (__id == null) {\n          throw new Error(\n            'The __id field must be present on each item passed to the setter. This indicates a bug in Relay.',\n          );\n        }\n        const newValueRecord = recordSourceProxy.get(__id);\n        if (newValueRecord == null) {\n          throw new Error(","sourceCodeStart":193,"sourceCodeEnd":229,"githubUrl":"https://github.com/facebook/relay/blob/668b1b85e06261aa3b58dabfc51f8b5524a70955/packages/relay-runtime/mutations/createUpdatableProxy.js#L193-L229","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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"],"exampleFix":"// before\nupdatable.viewer.friends.set(null);\n// after\nupdatable.viewer.friends.set([]);","handlingStrategy":"validation","validationCode":"function canSetPlural(value) {\n  return Array.isArray(value);\n}\nif (!canSetPlural(next)) throw new TypeError('Expected an array; use [] instead of null for plural linked fields');","typeGuard":"function isNonEmptyAssignable<T>(v: ReadonlyArray<T> | null | undefined): v is ReadonlyArray<T> {\n  return v != null;\n}","tryCatchPattern":"try {\n  field.set(next);\n} catch (e) {\n  if (e.message.includes('plural linked fields')) field.set(next ?? []);\n  else throw e;\n}","preventionTips":["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"],"tags":["relay","updater","graphql","linked-fields"],"backgroundTag":"invalid-null-assignment","analyzedSha":"668b1b85e06261aa3b58dabfc51f8b5524a70955","analyzedAt":"2026-09-02T19:57:20.783Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-10T02:17:09.455Z"}