facebook/relay · error

Relay: Unexpected event kind

Error message

Relay: Unexpected event kind

What it means

Exhaustiveness guard in eventShouldThrow: a FieldError event arrived whose kind is not one of the known cases (relay_resolver.error, relay_field_payload.error, missing_expected_data.throw/log, missing_required_field.throw/log). It never fires for well-formed Relay internals; it indicates a new or malformed event kind reached the error dispatcher, i.e. version skew or a corrupted record in the store.

Source

Thrown at packages/relay-runtime/util/handlePotentialSnapshotErrors.js:101

      }
    }
  }
}

function eventShouldThrow(event: FieldError): boolean {
  switch (event.kind) {
    case 'relay_resolver.error':
    case 'relay_field_payload.error':
      return event.shouldThrow && !event.handled;
    case 'missing_expected_data.throw':
    case 'missing_required_field.throw':
      return !event.handled;
    case 'missing_required_field.log':
    case 'missing_expected_data.log':
      return false;
    default:
      event.kind as empty;
      throw new Error('Relay: Unexpected event kind');
  }
}

function handlePotentialSnapshotErrors(
  environment: IEnvironment,
  fieldErrors: ?FieldErrors,
  loggingContext: unknown | void,
) {
  /**
   * Inside handleFieldErrors, we check for throwOnFieldError - but this fn logs the error anyway by default
   * which is why this still should run in any case there's errors.
   */
  if (fieldErrors != null) {
    handleFieldErrors(environment, fieldErrors, loggingContext);
  }
}

module.exports = {

View on GitHub (pinned to 668b1b85e0)

Solutions

1. Ensure the Relay runtime version that wrote the FieldError events matches the version reading them
2. Inspect the persisted record's kind field for unexpected/corrupted values
3. If you added a new FieldError kind in a fork, extend the switch in eventShouldThrow to handle it

When it happens

Trigger: Thrown at packages/relay-runtime/util/handlePotentialSnapshotErrors.js:101 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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