{"record":{"id":"243c3a1fbd8e05a8","repo":"TanStack/query","slug":"usepipwindow-must-be-used-within-a-pipprovider","errorCode":null,"errorMessage":"usePiPWindow must be used within a PiPProvider","messagePattern":"usePiPWindow must be used within a PiPProvider","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/query-devtools/src/contexts/PiPContext.tsx","lineNumber":199,"sourceCode":"  })\n\n  const value = createMemo(() => ({\n    pipWindow: pipWindow(),\n    requestPipWindow,\n    closePipWindow,\n    disabled: props.disabled ?? false,\n  }))\n\n  return (\n    <PiPContext.Provider value={value}>{props.children}</PiPContext.Provider>\n  )\n}\n\nexport const usePiPWindow = () => {\n  const context = createMemo(() => {\n    const ctx = useContext(PiPContext)\n    if (!ctx) {\n      throw new Error('usePiPWindow must be used within a PiPProvider')\n    }\n    return ctx()\n  })\n  return context\n}\n","sourceCodeStart":181,"sourceCodeEnd":205,"githubUrl":"https://github.com/TanStack/query/blob/159982c80b844487054155c38ffc760fe4208daf/packages/query-devtools/src/contexts/PiPContext.tsx#L181-L205","documentation":"Thrown by `usePiPWindow()` (the devtools PiP context hook) when `useContext(PiPContext)` returns `undefined`, meaning the hook was called outside a `<PiPProvider>`. This is the standard Solid context-missing-consumer guard: the hook needs the PiP signal/value that only the provider creates, and without it the consumer would dereference `undefined` immediately, so it throws early with an actionable message.","triggerScenarios":"Calling `usePiPWindow()` in a component that is rendered outside the `<PiPProvider>` subtree; importing `usePiPWindow` and using it in app code (it is an internal devtools hook); rendering a PiP-consuming component in a test without wrapping it in `PiPProvider`; module duplication where the `PiPContext` singleton differs between two copies of the devtools package.","commonSituations":"Internal devtools component accidentally imported into app code; tests rendering a devtools subcomponent in isolation without the provider tree; npm/pnpm hoisting causing two installations of `@tanstack/query-devtools` so the context object identity differs between provider and consumer; SSR rendering where the provider was conditionally skipped.","solutions":["Ensure the component calling `usePiPWindow()` is rendered inside `<PiPProvider>` (in the devtools, this is wired by the devtools tree itself — do not import this hook into app code).","If writing a test, wrap the rendered component in `<PiPProvider localStore={...} setLocalStore={...}>...</PiPProvider>`.","Deduplicate the devtools package — check `pnpm why @tanstack/query-devtools` / `npm ls` and align versions so the context singleton is shared.","Do not use `usePiPWindow` in application code; it is an internal hook. Use the public `<ReactQueryDevtools />` component instead."],"exampleFix":"// before - hook used outside provider\nconst ctx = usePiPWindow()\nreturn <Panel />\n\n// after - wrap with PiPProvider (internal devtools usage)\n<PiPProvider localStore={store} setLocalStore={setStore}>\n  <Panel />\n</PiPProvider>","handlingStrategy":"type-guard","validationCode":"// Verify context is present before calling the hook's body\nimport { useContext } from 'solid-js'\nimport { PiPContext } from '@tanstack/query-devtools'\nconst isInsidePiPProvider = () => useContext(PiPContext) !== undefined","typeGuard":"// Narrow before relying on the context value\nimport { useContext } from 'solid-js'\nimport { PiPContext } from '@tanstack/query-devtools'\nconst hasPiPContext = (): boolean => useContext(PiPContext) !== undefined","tryCatchPattern":"let ctx\ntry {\n  ctx = usePiPWindow()\n} catch (e) {\n  if (e.message === 'usePiPWindow must be used within a PiPProvider') {\n    // render without PiP, or wrap the tree in <PiPProvider> upstream\n    return null\n  }\n  throw e\n}","preventionTips":["Do not import usePiPWindow in application code; it is an internal devtools hook.","When testing internal devtools components, always wrap them in <PiPProvider>.","Deduplicate @tanstack/query-devtools across the dependency tree so the context singleton matches.","Render the provider once at the top of the devtools subtree, never conditionally below a consumer."],"tags":["devtools","pip","context","solid","provider"],"backgroundTag":null,"analyzedSha":"159982c80b844487054155c38ffc760fe4208daf","analyzedAt":"2026-08-12T16:21:52.822Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}