marmelab/react-admin · error · Error

useReferenceFieldController: missing reference prop. You mus

Error message

useReferenceFieldController: missing reference prop. You must provide a reference, e.g. reference="posts".

What it means

useReferenceFieldController powers <ReferenceField> and needs to know which resource the reference points to (e.g. 'users'). The `reference` option is mandatory; if it is undefined at call time react-admin throws immediately so the field fails fast instead of issuing a query against an undefined resource.

Source

Thrown at packages/ra-core/src/controller/field/useReferenceFieldController.ts:17

import { useMemo } from 'react';
import { UseQueryOptions } from '@tanstack/react-query';

import { RaRecord } from '../../types';
import { LinkToType, useGetPathForRecord } from '../../routing';
import { UseReferenceResult, useReference } from '../useReference';
import { useFieldValue } from '../../util';

export const useReferenceFieldController = <
    ReferenceRecordType extends RaRecord = RaRecord,
    ErrorType = Error,
>(
    options: UseReferenceFieldControllerOptions<ReferenceRecordType, ErrorType>
): UseReferenceFieldControllerResult<ReferenceRecordType, ErrorType> => {
    const { link, reference, queryOptions } = options;
    if (!reference) {
        throw new Error(
            'useReferenceFieldController: missing reference prop. You must provide a reference, e.g. reference="posts".'
        );
    }
    const id = useFieldValue(options);
    const referenceRecordQuery = useReference<ReferenceRecordType, ErrorType>({
        reference,
        id,
        options: {
            ...queryOptions,
            enabled:
                (queryOptions?.enabled == null ||
                    queryOptions?.enabled === true) &&
                id != null,
        },
    });

    const path = useGetPathForRecord({
        record: referenceRecordQuery.referenceRecord,

View on GitHub (pinned to 051f511bb0)

Solutions

1. Add the required reference prop to the field: <ReferenceField source="user_id" reference="users">.
2. If reference is dynamic, ensure the variable is defined and non-empty before rendering, or skip rendering the field while it is undefined.
3. Check spelling/prop forwarding when wrapping ReferenceField in a custom component so `reference` reaches the controller.

Example fix

// before
<ReferenceField source="user_id" />
// after
<ReferenceField source="user_id" reference="users" link="show">
  <TextField source="name" />
</ReferenceField>

// guard before rendering a dynamic reference field
if (!reference) return null; // or throw a descriptive error upstream
return <ReferenceField source={source} reference={reference}>{children}</ReferenceField>;

const hasReference = (props) =>
  typeof props?.reference === 'string' && props.reference.length > 0;

try {
  return <ReferenceField source={source} reference={reference} />;
} catch (e) {
  if (e.message.includes('missing reference prop')) {
    console.error(`ReferenceField for ${source} rendered without reference`);
    return null;
  }
  throw e;
}

When it happens

Trigger: Using <ReferenceField> without the `reference` prop, or passing reference={undefined} because it comes from an undefined variable / missing object key; calling useReferenceFieldController directly with an options object lacking `reference`.

Common situations: Building a generic field wrapper that spreads props but forgets to forward `reference`; destructuring config where the resource name key is misspelled (refrence/referencedResource); dynamically generated reference fields where an empty array/undefined entry is passed through.

Related errors

• Missing dataProvider prop. React-admin requires a valid data
• useShowController requires an id prop or a route with an /:i
• useNextPrevController was called outside of a ResourceContex
• <ReferenceArrayFieldBase> requires either a 'render' prop or
• <ReferenceFieldBase> requires either a 'render' prop or 'chi

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