{"record":{"id":"f1acfe1c72ec61ac","repo":"clockworklabs/SpacetimeDB","slug":"usespacetimedb-must-be-used-within-a-spacetimedbpr","errorCode":null,"errorMessage":"useSpacetimeDB must be used within a SpacetimeDBProvider component. Did you forget to add a `SpacetimeDBProvider` to your component tree?","messagePattern":"useSpacetimeDB must be used within a SpacetimeDBProvider component\\. Did you forget to add a `SpacetimeDBProvider` to your component tree\\?","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"crates/bindings-typescript/src/react/useSpacetimeDB.ts","lineNumber":13,"sourceCode":"import { createContext, useContext } from 'react';\nimport type { ConnectionState } from './connection_state';\n\nexport const SpacetimeDBContext = createContext<ConnectionState | undefined>(\n  undefined\n);\n\n// Throws an error if used outside of a SpacetimeDBProvider\n// Error is caught by other hooks like useTable so they can provide better error messages\nexport function useSpacetimeDB(): ConnectionState {\n  const context = useContext(SpacetimeDBContext) as ConnectionState | undefined;\n  if (!context) {\n    throw new Error(\n      'useSpacetimeDB must be used within a SpacetimeDBProvider component. Did you forget to add a `SpacetimeDBProvider` to your component tree?'\n    );\n  }\n  return context;\n}\n","sourceCodeStart":1,"sourceCodeEnd":19,"githubUrl":"https://github.com/clockworklabs/SpacetimeDB/blob/524b4487d949b61a07d4f39c862d1290259dfd20/crates/bindings-typescript/src/react/useSpacetimeDB.ts#L1-L19","documentation":"useSpacetimeDB reads the SpacetimeDBContext React context. When the context value is undefined - i.e. no SpacetimeDBProvider is mounted above the calling component - it throws immediately. Other hooks (useTable, useReducer, useProcedure) catch this error and rethrow it with their own guidance.","triggerScenarios":"Rendering a component that calls useSpacetimeDB (directly or via useTable/useReducer/useProcedure) outside a <SpacetimeDBProvider> subtree.","commonSituations":"Forgot to wrap the app in SpacetimeDBProvider; the provider is a sibling instead of an ancestor; a component rendered through a separate createRoot (dev overlay, modal micro-frontend, test render) that has no provider; unit tests rendering the component standalone.","solutions":["Wrap the component tree with <SpacetimeDBProvider> at a common ancestor (typically the app root)","In tests, wrap the render in the provider or mock the context before rendering hook-consuming components","Check that any separately-rooted UI (overlays, portals with their own root) is also inside a provider"],"exampleFix":"// before\nroot.render(<Dashboard />); // Dashboard uses useTable -> throws\n\n// after\nroot.render(\n  <SpacetimeDBProvider>\n    <Dashboard />\n  </SpacetimeDBProvider>\n);","handlingStrategy":"validation","validationCode":"// Ensure the provider is an ancestor of every hook consumer before rendering:\nroot.render(\n  <SpacetimeDBProvider>\n    <App />\n  </SpacetimeDBProvider>\n);","typeGuard":null,"tryCatchPattern":"// In an error boundary, degrade gracefully instead of crashing the tree:\nstatic getDerivedStateFromError(e: Error) {\n  return { missingProvider: e.message.includes('SpacetimeDBProvider') };\n}","preventionTips":["Mount SpacetimeDBProvider once at the app root","Wrap test renders of hook-consuming components in the provider (or mock the context)","Components rendered through a separate createRoot need their own provider subtree"],"tags":["react","hooks","context","typescript"],"backgroundTag":"react-context-provider-missing","analyzedSha":"524b4487d949b61a07d4f39c862d1290259dfd20","analyzedAt":"2026-08-16T23:58:54.611Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}