clockworklabs/SpacetimeDB · error · Error

useSpacetimeDB must be used within a component that called…

Error message

useSpacetimeDB must be used within a component that called createSpacetimeDBProvider. Did you forget to call `createSpacetimeDBProvider` in a parent component?

What it means

The Svelte bindings use Svelte's context API: createSpacetimeDBProvider(builder) runs setContext(SPACETIMEDB_CONTEXT_KEY, store) during a component's initialization, and useSpacetimeDB() runs getContext(SPACETIMEDB_CONTEXT_KEY). When getContext returns undefined — no ancestor called createSpacetimeDBProvider, or the call happened outside synchronous component init — the hook throws.

Solutions

Call createSpacetimeDBProvider(builder) synchronously during the root component's initialization (e.g. +layout.svelte) so all descendants resolve the context
Keep no `await` between the start of component setup and the createSpacetimeDBProvider call
Only use the hooks in components rendered by (below) the component that created the provider
For SvelteKit, create the provider once in the root +layout.svelte, not per page

Example fix

<!-- before: +page.svelte -->
<script lang="ts">
  import { useTable } from '@clockworklabs/spacetime-db-svelte';
  const [rows] = useTable(tables.player); // throws
</script>

<!-- after: +layout.svelte -->
<script lang="ts">
  import { createSpacetimeDBProvider } from '@clockworklabs/spacetime-db-svelte';
  const db = createSpacetimeDBProvider(builder);
</script>
<slot /> <!-- all child pages now resolve the context -->

Defensive patterns

Strategy: validation

Validate before calling

import { hasContext } from 'svelte';
import { SPACETIMEDB_CONTEXT_KEY } from './connection_state';

// inside a component's script, before using hooks:
if (!hasContext(SPACETIMEDB_CONTEXT_KEY)) {
  throw new Error('createSpacetimeDBProvider must be called in a parent component first');
}

Try / catch

// Context errors surface at component init; guard with hasContext() instead of catching

Prevention

Create the provider synchronously at the top of the root layout's script
Never place an await between component init and createSpacetimeDBProvider
Keep getContext-based hooks inside component initialization only

When it happens

Trigger: Calling useSpacetimeDB() (directly or via useTable/useReducer) in a Svelte component whose ancestors never called createSpacetimeDBProvider(builder); calling it from module scope, inside onMount, or after an await, since Svelte's getContext only works synchronously during component setup.

Common situations: SvelteKit apps where the provider was created in one +page.svelte but a sibling layout or another route needs it; calling the hook in a .svelte.ts module context; in Svelte 5, an await between component setup and createSpacetimeDBProvider invalidating the context; provider component created below the consumer.

Related errors

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

Appendix: source

Thrown at crates/bindings-typescript/src/svelte/useSpacetimeDB.ts:15

import { getContext } from 'svelte';
import type { Writable } from 'svelte/store';
import {
  SPACETIMEDB_CONTEXT_KEY,
  type ConnectionState,
} from './connection_state';

// Throws an error if used outside of a SpacetimeDBProvider
export function useSpacetimeDB(): Writable<ConnectionState> {
  const context = getContext<Writable<ConnectionState> | undefined>(
    SPACETIMEDB_CONTEXT_KEY
  );

  if (!context) {
    throw new Error(
      'useSpacetimeDB must be used within a component that called createSpacetimeDBProvider. ' +
        'Did you forget to call `createSpacetimeDBProvider` in a parent component?'
    );
  }

  return context;
}

View on GitHub (pinned to 6dee26c6ef)