{"record":{"id":"c62e29d8570f8b6c","repo":"tailwindlabs/headlessui","slug":"you-must-wrap-your-component-in-a-stablecollectio","errorCode":null,"errorMessage":"You must wrap your component in a <StableCollection>","messagePattern":"You must wrap your component in a <StableCollection>","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/@headlessui-react/src/utils/stable-collection.tsx","lineNumber":53,"sourceCode":"\n      return [index, release]\n    },\n  }\n}\n\nexport function StableCollection({ children }: { children: React.ReactNode | React.ReactNode[] }) {\n  let collection = React.useRef(createCollection())\n\n  return (\n    <StableCollectionContext.Provider value={collection}>\n      {children}\n    </StableCollectionContext.Provider>\n  )\n}\n\nexport function useStableCollectionIndex(group: string) {\n  let collection = React.useContext(StableCollectionContext)\n  if (!collection) throw new Error('You must wrap your component in a <StableCollection>')\n\n  let key = React.useId()\n  let [idx, cleanupIdx] = collection.current.get(group, key)\n  React.useEffect(() => cleanupIdx, [])\n  return idx\n}\n","sourceCodeStart":35,"sourceCodeEnd":60,"githubUrl":"https://github.com/tailwindlabs/headlessui/blob/eea57cf46fd6767ed1059012f7073b88eb159fba/packages/@headlessui-react/src/utils/stable-collection.tsx#L35-L60","documentation":"Headless UI's StableCollection assigns stable indices to sibling items (used e.g. by Tab/Menu keyboard ordering and SSR-consistent ordering). useStableCollectionIndex must run inside a component that is a descendant of <StableCollection>, which provides the context holding the index registry. If the context is absent, the hook throws this error — it is an internal invariant, not something user code normally triggers.","triggerScenarios":"Rendering an internal Headless UI child component that calls useStableCollectionIndex outside its expected <StableCollection> parent; library authors reusing Headless UI internals (importing from @headlessui/react internals) without the provider; version mismatches between @headlessui/react packages or duplicated copies causing two different StableCollectionContext instances; SSR hydration tree differences where the provider renders on one side only.","commonSituations":"Mixing @headlessui/react v1 and v2 components in one tree (or nested duplicates of the package via npm hoisting bugs); wrapping Headless UI internals in custom builds; monkey-patching or extracting components like Tab/Menu internals.","solutions":["Update @headlessui/react to a single consistent version across the project","Deduplicate the package: check npm ls @headlessui/react and add a resolution/override so only one copy exists","Avoid importing or re-exporting internal modules of @headlessui/react; use the public components which render StableCollection themselves","If it appears only on SSR, verify the component tree is identical server/client (no conditional provider based on typeof window)"],"exampleFix":"// before (mixing versions)\n// v2 <Tab.Group> renders v1 <Tab> internals → context mismatch\n\n// after\nnpm ls @headlessui/react\n// then in package.json:\n\"overrides\": { \"@headlessui/react\": \"^2.2.0\" }","handlingStrategy":"validation","validationCode":"import pkg from '@headlessui/react/package.json';\n// fail fast at startup in dev\nif (!pkg.version.startsWith('2.')) console.warn('unexpected @headlessui/react version', pkg.version);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pin one version of @headlessui/react and dedupe dependencies","Never import from internal module paths","Keep provider/component trees identical on server and client for SSR"],"tags":["headlessui","react","context","ssr","dependency-mismatch"],"backgroundTag":"missing-context-provider","analyzedSha":"eea57cf46fd6767ed1059012f7073b88eb159fba","analyzedAt":"2026-08-28T19:22:46.163Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}