marmelab/react-admin · error

<ReferenceFieldBase> requires either a 'render' prop or 'chi

Error message

<ReferenceFieldBase> requires either a 'render' prop or 'children' prop

What it means

ReferenceFieldBase is the headless core of <ReferenceField>; it must be told how to render the resolved reference record via a render prop or children. When neither is present the component would render nothing, so react-admin throws immediately during render.

Source

Thrown at packages/ra-core/src/controller/field/ReferenceFieldBase.tsx:57

 * <ReferenceFieldBase source="userId" reference="users" link={(record, reference) => "/path/to/${reference}/${record}"} />
 *
 * @default
 * In previous versions of React-Admin, the prop `linkType` was used. It is now deprecated and replaced with `link`. However
 * backward-compatibility is still kept
 */
export const ReferenceFieldBase = <
    ReferenceRecordType extends RaRecord = RaRecord,
>(
    props: ReferenceFieldBaseProps<ReferenceRecordType>
) => {
    const { children, render, loading, error, empty, offline } = props;
    const id = useFieldValue(props);

    const controllerProps =
        useReferenceFieldController<ReferenceRecordType>(props);

    if (!render && !children) {
        throw new Error(
            "<ReferenceFieldBase> requires either a 'render' prop or 'children' prop"
        );
    }

    const {
        error: controllerError,
        isPending,
        isPaused,
        referenceRecord,
    } = controllerProps;
    const shouldRenderLoading =
        id != null &&
        !isPaused &&
        isPending &&
        loading !== false &&
        loading !== undefined;
    const shouldRenderOffline =
        isPaused && isPending && offline !== false && offline !== undefined;

View on GitHub (pinned to 051f511bb0)

Solutions

1. Add children: <ReferenceFieldBase source="user_id" reference="users"><TextField source="name" /></ReferenceFieldBase>
2. Or add a render prop: <ReferenceFieldBase source="user_id" reference="users" render={({referenceRecord}) => ...} />
3. Verify the children expression is truthy at runtime when it is conditional

Example fix

// before
<ReferenceFieldBase source="user_id" reference="users" />
// after
<ReferenceFieldBase source="user_id" reference="users">
  <TextField source="name" />
</ReferenceFieldBase>

const assertRenderable = (p: { render?: unknown; children?: unknown }) => {
  if (p.render == null && p.children == null)
    throw new Error('Provide render or children');
};

const canRender = (p: { render?: unknown; children?: unknown }): boolean =>
  Boolean(p.render ?? p.children);

try {
  render(<ReferenceFieldBase source="user_id" reference="users" />);
} catch (e) { logAndFallback(e); }

When it happens

Trigger: Using <ReferenceFieldBase source="user_id" reference="users" /> without render or children; passing children that evaluate to undefined (conditional JSX, a variable that is null); forgetting the child when migrating from an older field API.

Common situations: Building a custom field on top of the headless base component and forgetting the render layer; dynamic children like {enabled && <Child/>} that resolve to false; copying ra-ui-materialist <ReferenceField> usage but calling the ra-core base directly.

Related errors

• <ReferenceArrayFieldBase> requires either a 'render' prop or
• <ReferenceManyFieldBase> requires either a 'render' prop or
• <ReferenceOneFieldBase> requires either a 'render' prop or '
• <ReferenceArrayInputBase> requires either a 'render' prop or
• useReferenceFieldController: missing reference prop. You mus

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