`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` in `createTableHookContexts.tsx` reads `headerContext` provided by `<table.AppHeader>` or `<table.AppFooter>`. With no such provider above the caller, the context is undefined and this error is thrown, ensuring header APIs are only used with a real header instance.

Source

Thrown at packages/react-table/src/createTableHookContexts.tsx:154

    }

    return cell as unknown as Cell<TFeatures, any, TValue>
  }

  /**
   * Access the header instance from within an `AppHeader` or `AppFooter` wrapper
   * bound to these scoped contexts.
   */
  function useHeaderContext<TValue extends CellData = CellData>(): Header<
    TFeatures,
    any,
    TValue
  > {
    // eslint-disable-next-line @eslint-react/no-use-context -- intentional for React 18
    const header = useContext(headerContext)

    if (!header) {
      throw new Error(
        '`useHeaderContext` must be used within an `AppHeader` or `AppFooter` component.',
      )
    }

    return header as unknown as Header<TFeatures, any, TValue>
  }

  return {
    // Re-typed without `| null` so they drop straight into `createTableHook`'s
    // `tableContext`/`cellContext`/`headerContext` options.
    tableContext: tableContext as unknown as Context<ReactTable<any, any>>,
    cellContext: cellContext as unknown as Context<Cell<any, any, any>>,
    headerContext: headerContext as unknown as Context<Header<any, any, any>>,
    useTableContext,
    useCellContext,
    useHeaderContext,
  }
}

View on GitHub (pinned to d01c01bedb)

Solutions

Wrap the component with `<table.AppHeader header={header}>` or `<table.AppFooter header={header}>`.
Move the component into the provider's children.
Dedupe the table package so the context module identity is shared.
Use `useContext(headerContext)` directly with a null check when the header may be absent.

Example fix

// before
function HeaderLabel() {
  const header = useHeaderContext()
  return <span>{header.column.columnDef.header}</span>
}

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

Defensive patterns

Strategy: validation

Validate before calling

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

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
  }
  throw err
}

Prevention

Render header consumers inside table.AppHeader/table.AppFooter only.
Pair provider and consumer in a wrapper component.
Dedupe package versions.
Test with provider-aware mounting helpers.

When it happens

Trigger: Calling `useHeaderContext()` outside AppHeader/AppFooter; rendering through a portal or a second root; duplicate installs of the package with distinct context objects.

Common situations: Custom header controls placed in a plain wrapper after refactor; storybook isolation mounts; version skew across workspaces.

Related errors

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