clockworklabs/SpacetimeDB · error · Error

useSpacetimeDB must be used within a SpacetimeDBProvider…

Error message

useSpacetimeDB must be used within a SpacetimeDBProvider component. Did you forget to add a `SpacetimeDBProvider` to your component tree?

What it means

The Solid bindings distribute SpacetimeDB connection state through a Solid context (SpacetimeDBContext). useSpacetimeDB() reads it with useContext(), and Solid returns undefined when no matching Provider exists above the calling component, so the hook throws to fail fast. The throw is intentionally loud: sibling hooks such as useTable catch it and rethrow with their own guidance.

Solutions

Wrap the tree with <SpacetimeDBProvider connectionBuilder={builder}> so every hook consumer is a descendant of it
In tests, render the component under test inside SpacetimeDBProvider before asserting on table data
Verify the provider sits ABOVE (not beside or below) every component calling useTable/useSpacetimeDB
If you must use createRoot/portals, render the consumer inside the provider subtree or pass the context value explicitly

Example fix

// before
export default function App() {
  return <PlayerList />; // PlayerList calls useTable -> throws
}

// after
import { SpacetimeDBProvider } from '@clockworklabs/spacetime-db-solid';

export default function App() {
  return (
    <SpacetimeDBProvider connectionBuilder={builder}>
      <PlayerList />
    </SpacetimeDBProvider>
  );
}

Defensive patterns

Strategy: validation

Validate before calling

import { useContext } from 'solid-js';
import { SpacetimeDBContext } from './solid/useSpacetimeDB';

export function hasSpacetimeDB(): boolean {
  return useContext(SpacetimeDBContext) !== undefined;
}

// before calling hooks:
if (!hasSpacetimeDB()) throw new Error('Mount this component under <SpacetimeDBProvider>');

Type guard

import { useContext } from 'solid-js';
import { SpacetimeDBContext, type ConnectionState } from './solid/useSpacetimeDB';

export function tryGetConnection(): ConnectionState | undefined {
  return useContext(SpacetimeDBContext); // undefined instead of throwing
}

Try / catch

// hooks run during render; catch with Solid's ErrorBoundary
<ErrorBoundary fallback={(err) => <p>SpacetimeDB setup missing: {err.message}</p>}>
  <PlayerList />
</ErrorBoundary>

Prevention

Add SpacetimeDBProvider at the app root as the first integration step, before any useTable calls
Create a test wrapper component that always includes the provider
Convention: any file importing useTable/useSpacetimeDB must render below the provider

When it happens

Trigger: Calling useSpacetimeDB() directly, or any hook that wraps it (useTable, useReducer, useProcedure), in a component that is not a descendant of <SpacetimeDBProvider connectionBuilder={builder}>. Also occurs when a consumer is mounted via createRoot() or a portal outside the provider subtree, or when a second app root is mounted without its own provider.

Common situations: SolidStart/SolidKit apps where the provider was added to one route layout but a shared widget renders outside it; unit tests rendering a single component without the provider; reordering the tree so the provider ends up below the consumer; mixing the Solid provider with hooks imported from the React bindings.

Related errors

AI-assisted analysis of clockworklabs/SpacetimeDB@6dee26c6ef (2026-08-20). Data as JSON: /api/errors/2689f1ad91fd79b4. Report an issue: GitHub.

Appendix: source

Thrown at crates/bindings-typescript/src/solid/useSpacetimeDB.ts:13

import { createContext, useContext } from 'solid-js';
import type { ConnectionState } from './connection_state';

export const SpacetimeDBContext = createContext<ConnectionState | undefined>(
  undefined
);

// Throws an error if used outside of a SpacetimeDBProvider
// Error is caught by other hooks like useTable so they can provide better error messages
export function useSpacetimeDB(): ConnectionState {
  const context = useContext(SpacetimeDBContext) as ConnectionState | undefined;
  if (!context) {
    throw new Error(
      'useSpacetimeDB must be used within a SpacetimeDBProvider component. Did you forget to add a `SpacetimeDBProvider` to your component tree?'
    );
  }
  return context;
}

View on GitHub (pinned to 6dee26c6ef)