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

Error message

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

What it means

Octane's useHeaderContext reads the header from React context provided by <table.AppHeader> or <table.AppFooter>. If neither provider is above the hook call, the header is undefined and this error is thrown.

Source

Thrown at packages/octane-table/src/createTableHookContexts.ts:125

      )
    }

    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
  > {
    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<OctaneTable<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 consuming component in <table.AppHeader header={header}> or <table.AppFooter footer={footer}>
Use the correct hook for the slot (useCellContext in cells, useTableContext at table level)
Pass the header explicitly as a prop if rendering outside the provider

Example fix

// before
const header = useHeaderContext(); // throws in cell
// after
<table.AppHeader header={header}>
  <MyHeaderContent /> // useHeaderContext() works here
</table.AppHeader>

Defensive patterns

Strategy: validation

Validate before calling

const header = useContextSafe(headerContext);
if (!header) throw new Error('useHeaderContext requires <table.AppHeader> or <table.AppFooter>');

Type guard

function isHeader(h: unknown): h is Header<any, any, any> {
  return !!h && typeof h === 'object' && 'column' in h && 'depth' in h;
}

Try / catch

try {
  const header = useHeaderContext();
} catch (e) {
  if (e.message.includes('AppHeader')) {
    // use header prop or switch to the correct slot hook
  } else { throw e; }
}

Prevention

Use useHeaderContext only in AppHeader/AppFooter-wrapped components
Use useCellContext in cells — the header hook will throw there
Pass header/footer objects as props for out-of-tree rendering

When it happens

Trigger: Calling useHeaderContext() from a component not wrapped in <table.AppHeader> or <table.AppFooter>; using a header component in a cell or body slot; rendering headers via portals outside the provider subtree.

Common situations: Shared header/footer components used outside the table; mistakenly using useHeaderContext in a cell renderer (which provides cell, not header, context).

Related errors

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