marmelab/react-admin · error

useReferenceFieldContext must be used inside a ReferenceFiel

Error message

useReferenceFieldContext must be used inside a ReferenceFieldContextProvider

What it means

useReferenceFieldContext reads the context that <ReferenceField> sets up to share the resolved reference record and link info with its children. The hook throws when no ReferenceFieldContextProvider exists above it, i.e. it is called outside a <ReferenceField> subtree.

Source

Thrown at packages/ra-core/src/controller/field/ReferenceFieldContext.tsx:12

import { createContext, useContext } from 'react';
import type { UseReferenceFieldControllerResult } from './useReferenceFieldController';

export const ReferenceFieldContext =
    createContext<UseReferenceFieldControllerResult | null>(null);

export const ReferenceFieldContextProvider = ReferenceFieldContext.Provider;

export const useReferenceFieldContext = () => {
    const context = useContext(ReferenceFieldContext);
    if (!context) {
        throw new Error(
            'useReferenceFieldContext must be used inside a ReferenceFieldContextProvider'
        );
    }
    return context;
};

View on GitHub (pinned to 051f511bb0)

Solutions

1. Move the consuming component so it is rendered inside <ReferenceField>...</ReferenceField>
2. Use useRecordContext instead if you only need the current record and not the reference-link context
3. In tests, wrap with <ReferenceFieldContextProvider value={fakeValue}>

Example fix

// before
const UserName = () => {
  const { referenceRecord } = useReferenceFieldContext(); // throws outside ReferenceField
  ...
};
<List><UserName /></List>
// after
<List>
  <ReferenceField source="user_id" reference="users">
    <UserName />
  </ReferenceField>
</List>

const ctx = useContext(ReferenceFieldContext);
if (!ctx) return null; // avoid hook misuse downstream

const isRefFieldCtx = (c: unknown): c is { referenceRecord: RaRecord } =>
  !!c && typeof c === 'object' && 'referenceRecord' in c;

function Guard() {
  const ctx = useContext(ReferenceFieldContext);
  return ctx ? <UsesHook /> : null;
}

When it happens

Trigger: Calling useReferenceFieldContext() in a child rendered outside <ReferenceField> (e.g. used in a plain list row, a show view outside any reference field, or a storybook render without ReferenceFieldContextProvider).

Common situations: Extracting a child component of ReferenceField into a shared component and reusing it elsewhere; rendering the child in isolation in tests; nesting issues where the component is a sibling rather than a descendant of ReferenceField.

Related errors

• useArrayInput must be used inside an ArrayInputContextProvid
• useSimpleFormIterator must be used inside a SimpleFormIterat
• useSimpleFormIteratorItem must be used inside a SimpleFormIt
• useEditContext must be used inside an EditContextProvider
• useCreateSuggestionContext must be used inside a CreateSugge

AI-assisted analysis of marmelab/react-admin@051f511bb0 (2026-08-30). Data as JSON: /api/errors/9ffe14dfa052b1d4. Report an issue: GitHub.