mastra-ai/mastra · error · Error

SankeyChart must be used within Sankey

Error message

SankeyChart must be used within Sankey

What it means

useSankeyRenderContext reads SankeyRenderContext, which supplies the computed graph, enabledColumns, hueMap, and fixed-geometry flags used to render the diagram. The context defaults to null and is only populated by <Sankey>, so calling this hook outside a Sankey render tree throws this error. Unlike useSankey (controls), this hook exposes internal render geometry and is only meaningful within the chart.

Solutions

1. Ensure the consumer is rendered inside the <Sankey> component tree (e.g., via its render props/children API).
2. Pass graph/columns/hueMap explicitly via props if the component must live outside the chart.
3. Wrap isolated stories or tests with <Sankey> before rendering consumers of this hook.
4. Fix conditional rendering so the Sankey provider never unmounts while render-dependent children remain mounted.

Example fix

// before
<Sankey data={data} />
<CustomNodeLabel /> {/* useSankeyRenderContext() throws */}

// after
<Sankey data={data}>
  <CustomNodeLabel />
</Sankey>

const render = useContext(SankeyRenderContext);
if (!render) {
  // not inside <Sankey>: render placeholder instead of using graph/hueMap
}

const hasRenderContext = (v: SankeyRenderContextValue | null): v is SankeyRenderContextValue => v != null;

try {
  const render = useSankeyRenderContext();
  drawOverlay(render.graph, render.hueMap);
} catch {
  // outside <Sankey>: skip overlay
}

When it happens

Trigger: Invoking useSankeyRenderContext() from a custom node/link renderer, tooltip, or overlay mounted outside <Sankey>; using it in a story/test that renders components in isolation; calling it in a component that renders before Sankey mounts its render context.

Common situations: Building custom SVG overlays over the sankey diagram and placing them as siblings rather than children; extracting the chart's tooltip into a separate route; snapshot tests rendering a node component without the chart wrapper.

Related errors

• useSankey must be used within Sankey
• must be used within MessageScrollerProvider.
• Plan compound components must be rendered inside
• ToolCall compounds must be rendered within ToolCall
• Comment compounds must be rendered within Comment

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/6324e30dd9c2ca9b. Report an issue: GitHub.

Appendix: source

Thrown at packages/playground-ui/src/ds/components/SankeyChart/sankey-context.tsx:131

      >
        {children}
      </SankeyRenderContext.Provider>
    </SankeyControlsContext.Provider>
  );
}

// Context providers and their hooks intentionally share this module.
// eslint-disable-next-line react-refresh/only-export-components
export function useSankey() {
  const context = useContext(SankeyControlsContext);
  if (!context) throw new Error('useSankey must be used within Sankey');
  return context;
}

// eslint-disable-next-line react-refresh/only-export-components
export function useSankeyRenderContext() {
  const context = useContext(SankeyRenderContext);
  if (!context) throw new Error('SankeyChart must be used within Sankey');
  return context;
}

function orderColumns(columns: Array<SankeyChartColumn>, order: Array<string>) {
  const positions = new Map(order.map((id, index) => [id, index]));
  return [...columns].sort(
    (left, right) => (positions.get(left.id) ?? columns.length) - (positions.get(right.id) ?? columns.length),
  );
}

View on GitHub (pinned to 75dd419e61)