`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 the Octane table injects the header context provided only by `<table.AppHeader>` or `<table.AppFooter>`. If absent, the hook throws rather than returning a null header. This catches header components rendered outside their required provider at the point of use.

Source

Thrown at packages/octane-table/src/createTableHook.tsrx:253

	}

	/**
 * Access the header instance from within an `AppHeader` or `AppFooter`
 * wrapper. Use this in custom `headerComponents` passed to `createTableHook`.
 *
 * @example
 * ```tsx
 * function SortIndicator() @{
 *   const header = useHeaderContext()
 *   <span>{(header.column.getIsSorted() || '') as string}</span>
 * }
 * ```
 */
	function useHeaderContext<TValue extends CellData = CellData>() {
		const header = useContext(HeaderContext);

		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: () => OctaneNode;
			};
	}

	/** Context-aware FlexRender for cells — reads the cell from context. */
	function CellFlexRender() {
		const cell = useCellContext();
		return <FlexRender cell={cell} />;
	}

	/** Context-aware FlexRender for headers — reads the header from context. */
	function HeaderFlexRender() {

View on GitHub (pinned to d01c01bedb)

Solutions

Render the component inside `<table.AppHeader>` or `<table.AppFooter>`.
Switch to `useCellContext` if the component is a cell child.
Pass the header as a prop instead of reading context.

Example fix

// before
<HeaderBody /> // calls useHeaderContext()
// after
<table.AppHeader header={header}>
  <HeaderBody />
</table.AppHeader>

Defensive patterns

Strategy: validation

Validate before calling

const header = useContext(HeaderContext)
if (!header) {
  console.warn('Component must be rendered inside <table.AppHeader> or <table.AppFooter>')
}

Type guard

function hasHeaderContext(h: unknown): h is NonNullable<typeof h> {
  return h != null
}

Try / catch

try {
  const header = useHeaderContext()
} catch (e) {
  if (e instanceof Error && e.message.includes('useHeaderContext')) {
    // fallback UI
  } else throw e
}

Prevention

Render header/footer components only within AppHeader/AppFooter
Match hook to scope: useCellContext in cells, useHeaderContext in headers
Pass header as prop when the component must render outside the table
Keep extracted components close to their provider usage

When it happens

Trigger: Calling `useHeaderContext()` in a component not rendered inside `<table.AppHeader>`/`<table.AppFooter>` — e.g. under AppTable directly, inside AppCell, or in a portal escaping the header subtree.

Common situations: Extracting header/footer markup into a separate component without the AppHeader wrapper; using the wrong hook (this instead of useCellContext); migrating from a props-based header API and leaving the hook in place.

Related errors

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