mantinedev/mantine · critical · Error

useFormContext was called outside of FormProvider context

Error message

useFormContext was called outside of FormProvider context

What it means

useFormContext is a hook that reads React context created by createFormContext(). It throws when called in a component that is not rendered inside the corresponding FormProvider, because the context value is undefined. The library throws instead of returning undefined to fail fast on invalid form usage.

Solutions

Wrap the component tree (including all components that call useFormContext) in the FormProvider returned from the same createFormContext() call: <FormProvider form={form}>...</FormProvider>
If the component can render standalone, pass the form object down as a prop instead of reading it from context
In tests, wrap the rendered component in the FormProvider (or a custom render helper that does so)
Make sure you are using the useFormContext exported from the same createFormContext module, not from a different form instance

Example fix

// before
function MyForm() {
  const form = useFormContext(); // throws
  return <input {...form.getInputProps('name')} />;
}

// after
function App() {
  const form = useForm({ initialValues: { name: '' } });
  return (
    <FormProvider form={form}>
      <MyForm />
    </FormProvider>
  );
}

Defensive patterns

Strategy: validation

Validate before calling

import { FormProvider, useFormContext } from './form-context';

function useOptionalForm() {
  const el = useRef<HTMLDivElement>(null);
  // Context presence must be checked by the provider structure itself;
  // you can detect it before calling the hook only by static tree inspection:
  // ensure <FormProvider> is an ancestor in JSX.

Type guard

// Not possible at runtime before calling the hook (hooks cannot be conditional).
// Static guard: verify the JSX tree wraps consumers in <FormProvider>.
const isInsideProvider = (node: React.ReactNode): boolean =>
  /* walk React element tree checking for FormProvider type */ true;

Try / catch

// Wrap the consuming component if it must render outside the provider
function SafeInput(props) {
  try {
    // hooks can't be called in try/catch — instead guard by structure:
    return <InputWithForm {...props} />;
  } catch {
    return <PlainInput {...props} />;
  }
}
// Prefer: always render inside <FormProvider> or pass form as prop.

Prevention

Always render the provider at the common ancestor of every useFormContext consumer
Create a custom test render that includes FormProvider by default
Use TypeScript: keep useFormContext consumers in the same module tree as the provider component
For optionally-connected components, accept the form via props with a context fallback pattern

When it happens

Trigger: Calling useFormContext() (returned from createFormContext) in a component that is not a descendant of the FormProvider component from the same createFormContext call. Also happens when nesting providers incorrectly or using useFormContext from a different createFormContext instance whose provider is not above the consumer.

Common situations: Rendering form fields outside the <FormProvider> wrapper (e.g. in a sibling component, portal root, or modal rendered outside the form tree); forgetting to wrap the component tree in FormProvider after refactoring; mixing up useFormContext from two separate createFormContext calls; testing a component in isolation without the provider.

Related errors

AI-assisted analysis of mantinedev/mantine@8a284e2c2c (2026-08-28). Data as JSON: /api/errors/ec3121f10b11d284. Report an issue: GitHub.

Appendix: source

Thrown at packages/@mantine/form/src/FormProvider/FormProvider.tsx:22

export interface FormProviderProps<Form> {
  form: Form;
  children: React.ReactNode;
}

export function createFormContext<Values, TransformedValues = Values, Rules = any>() {
  type Form = UseFormReturnType<Values, TransformedValues, Rules>;

  const FormContext = createContext<Form | null>(null);

  function FormProvider({ form, children }: FormProviderProps<Form>) {
    return <FormContext value={form}>{children}</FormContext>;
  }

  function useFormContext() {
    const ctx = use(FormContext);
    if (!ctx) {
      throw new Error('useFormContext was called outside of FormProvider context');
    }

    return ctx;
  }

  return [FormProvider, useFormContext, useForm] as [
    React.FC<FormProviderProps<Form>>,
    () => Form,
    UseForm<Values, TransformedValues, Rules>,
  ];
}

View on GitHub (pinned to 8a284e2c2c)