facebook/relay · error

useRefetchableFragmentNode: Unexpected action type

Error message

useRefetchableFragmentNode: Unexpected action type

What it means

useRefetchableFragmentNode manages refetch state through a useReducer whose reducer handles a fixed set of action types (e.g. 'refetch', 'loading', 'reset'). Reaching the default branch means an action with an unknown type was dispatched — Relay treats this as an internal invariant violation / bug in Relay or in a wrapper that dispatches custom actions into its state.

Source

Thrown at packages/react-relay/relay-hooks/useRefetchableFragmentInternal.js:158

        onComplete: action.onComplete,
        refetchEnvironment: action.refetchEnvironment,
        refetchQuery: action.refetchQuery,
        renderPolicy: action.renderPolicy,
      };
    }
    case 'reset': {
      return {
        fetchPolicy: undefined,
        mirroredEnvironment: action.environment,
        mirroredFragmentIdentifier: action.fragmentIdentifier,
        onComplete: undefined,
        refetchQuery: null,
        renderPolicy: undefined,
      };
    }
    default: {
      action.type as empty;
      throw new Error('useRefetchableFragmentNode: Unexpected action type');
    }
  }
}

hook useRefetchableFragmentInternal<
  TQuery extends OperationType,
  TKey extends ?{readonly $data?: unknown, ...},
>(
  fragmentNode: ReaderFragment,
  parentFragmentRef: unknown,
  componentDisplayName: string,
): ReturnType<TQuery, TKey, InternalOptions> {
  const parentEnvironment = useRelayEnvironment();
  const {refetchableRequest, fragmentRefPathInResponse, identifierInfo} =
    getRefetchMetadata(fragmentNode, componentDisplayName);
  const fragmentIdentifier = getFragmentIdentifier(
    fragmentNode,
    parentFragmentRef,

View on GitHub (pinned to 668b1b85e0)

Solutions

1. Run 'npm ls react-relay relay-runtime' (or yarn why) and deduplicate so react-relay and relay-runtime are the same version
2. Delete node_modules and lockfile and reinstall to clear duplicate relay packages
3. Remove any custom code/tests that dispatch unknown actions into Relay's internal reducer
4. If reproducible on matching versions, file a Relay bug with a reproduction (this is an internal invariant)

Example fix

// before (package.json)
"react-relay": "14.1.0",
"relay-runtime": "13.2.0"
// after
"react-relay": "14.1.0",
"relay-runtime": "14.1.0"

import pkg from 'react-relay/package.json';
import rt from 'relay-runtime/package.json';
if (pkg.version !== rt.version) throw new Error('react-relay/relay-runtime version mismatch: ' + pkg.version + ' vs ' + rt.version);

When it happens

Trigger: The reducer in useRefetchableFragmentInternal.js receives an action whose type matches none of its cases — typically caused by a Relay version mismatch (react-relay dispatching action shapes a different relay-runtime/relay-hooks version doesn't know), or code monkey-patching/forwarding foreign actions into the hook's reducer.

Common situations: Mismatched versions of react-relay, relay-runtime, and relay-hooks packages in node_modules (duplicated installs); patched or mocked Relay internals in tests; custom forks of useRefetchableFragment that emit new action types.

Related errors

• MatchContainer: Expected `match` value to be an object or nu
• MatchContainer: Invalid 'match' value, expected an object th
• commitMutation: Expected mutation to be of type request
• Encountered an unexpected ReaderSelection variant in RelayRe
• LiveResolverCache: `ServerWeak` normalization info must not

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