`useHeaderContext` must be used within an `AppHeader` or `Ap

Error message

`useHeaderContext` must be used within an `AppHeader` or `AppFooter` component.

What it means

`useHeaderContext` reads the React header context provided by `<table.AppHeader>` or `<table.AppFooter>`. When the hook runs without such a provider above it, the context is undefined and the library throws. AppHeader/AppFooter also attach `headerComponents` and `FlexRender` onto the header instance, so using the hook outside them means those APIs are unavailable too.

Source

Thrown at packages/react-table/src/createTableHook.tsx:890

   *   if (!header.column.getCanFilter()) return null
   *   return (
   *     <input
   *       value={(header.column.getFilterValue() ?? '') as string}
   *       onChange={(e) => header.column.setFilterValue(e.target.value)}
   *       placeholder="Filter..."
   *     />
   *   )
   * }
   * ```
   */
  function useHeaderContext<TValue extends CellData = CellData>() {
    // `useContext` keeps React 18 support; `use(Context)` is React 19+ only.
    // eslint-disable-next-line @eslint-react/no-use-context -- intentional for React 18
    const header = useContext(HeaderContext)

    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
    if (!header) {
      throw new Error(
        '`useHeaderContext` must be used within an `AppHeader` or `AppFooter` component.',
      )
    }

    // `<table.AppHeader>` / `<table.AppFooter>` Object.assign `headerComponents`
    // and `FlexRender` onto the same header instance they provide.
    return header as unknown as Header<TFeatures, any, TValue> &
      THeaderComponents & { FlexRender: () => ReactNode }
  }

  /**
   * Context-aware FlexRender component for cells.
   * Uses the cell from context, so no need to pass cell prop.
   */
  function CellFlexRender() {
    const cell = useCellContext()
    return <FlexRender cell={cell} />
  }

View on GitHub (pinned to d01c01bedb)

Solutions

Wrap the component with `<table.AppHeader header={header}>` (or AppFooter) at the usage site.
Move the component into the children of AppHeader/AppFooter.
Dedupe the table package versions so all code shares one context module.
Read the raw context via `useContext(HeaderContext)` and handle null if usage is optional.

Example fix

// before
function SortButton() {
  const header = useHeaderContext()
  return <button onClick={() => header.column.toggleSorting()}>Sort</button>
}

// after
<table.AppHeader header={header}>
  <SortButton />
</table.AppHeader>

Defensive patterns

Strategy: validation

Validate before calling

import { useContext } from 'react'
import { HeaderContext } from '@your-scope/react-table'

function useSafeHeader() {
  const header = useContext(HeaderContext)
  if (!header) {
    console.error('useHeaderContext requires <table.AppHeader> or <table.AppFooter> above this component')
  }
  return header
}

Type guard

function hasHeader<T>(h: T | null | undefined): h is T {
  return h != null
}

Try / catch

try {
  const header = useHeaderContext()
  // use header
} catch (err) {
  if (err instanceof Error && err.message.includes('useHeaderContext')) {
    return null // not inside AppHeader/AppFooter
  }
  throw err
}

Prevention

Render header consumers as children of table.AppHeader/table.AppFooter only.
Pair provider and consumer in one wrapper component.
Check for duplicate package versions.
Use a provider-aware test mount helper.

When it happens

Trigger: Calling `useHeaderContext()` from a component not rendered inside `<table.AppHeader header={header}>` or `<table.AppFooter header={header}>`; portal-rendered consumers; duplicated package installs splitting context identity.

Common situations: Custom sort/resize handles placed outside the header wrapper; a shared header component used in a plain div during refactor; isolated test mounts without the provider.

Related errors

AI-assisted analysis of TanStack/table@d01c01bedb (2026-08-28). Data as JSON: /api/errors/01225c4ab97d978f. Report an issue: GitHub.