clockworklabs/SpacetimeDB · critical
v2 subscriptions without a module host are not supported yet
Error message
v2 subscriptions without a module host are not supported yet
What it means
The subscription actor's add_v2_subscription takes `host: Option<&ModuleHost>` and delegates ws_v2 Subscribe messages to the module host, because v2 subscriptions execute module view code. When the actor holds no ModuleHost for the database, the None arm panics ('not supported yet'). The panic happens server-side while processing a client subscribe, instead of returning a DBError to the client, so the actor task crashes.
Source
Thrown at crates/core/src/subscription/module_subscription_actor.rs:1269
)
}
/// Add a subscription consisting of multiple queries.
///
/// Read more in [`Self::add_single_subscription`].
#[tracing::instrument(level = "trace", skip_all)]
pub async fn add_v2_subscription(
&self,
host: Option<&ModuleHost>,
sender: Arc<ClientConnectionSender>,
auth: AuthCtx,
request: ws_v2::Subscribe,
timer: Instant,
_assert: Option<AssertTxFn>,
) -> Result<Option<ExecutionMetrics>, DBError> {
match host {
Some(host) => host.call_view_add_v2_subscription(sender, auth, request, timer).await,
None => panic!("v2 subscriptions without a module host are not supported yet"),
}
}
/// Add a subscription consisting of multiple queries.
///
/// Read more in [`Self::add_single_subscription`].
#[tracing::instrument(level = "trace", skip_all)]
pub async fn add_multi_subscription(
&self,
host: Option<&ModuleHost>,
sender: Arc<ClientConnectionSender>,
auth: AuthCtx,
request: ws_v1::SubscribeMulti,
timer: Instant,
_assert: Option<AssertTxFn>,
) -> Result<Option<ExecutionMetrics>, DBError> {
match host {
Some(host) => {
host.call_view_add_multi_subscription(sender, auth, request, timer)View on GitHub (pinned to 9e0d92412f)
Solutions
- Publish a module for the database and confirm the host is running (`spacetime logs`, server status) before clients subscribe.
- Retry the subscription client-side with backoff until the module host is available.
- Ensure the client SDK's subscription protocol version is supported by the server/database state.
- Upgrade spacetimedb: newer builds convert this into a structured client error instead of a panic.
Defensive patterns
Strategy: validation
Validate before calling
// client: only issue v2 subscribes once the module host is live
// (adapt the status check to your SDK's database info API)
const status = await server.getDatabaseStatus(dbId);
if (status?.moduleHostState !== 'running') {
throw new Error(`module host not running (${status?.moduleHostState}); publish before subscribing`);
}
await client.subscription.subscribe(dbId, queries); // v2 path Prevention
- Publish the module and wait for it to become healthy before clients subscribe.
- Gate v2 subscription usage on a confirmed module deployment.
- Add reconnect-with-backoff so clients that race a module update resubscribe once the host is back.
- Avoid subscribing to databases that intentionally have no module.
When it happens
Trigger: A client sends a ws_v2 Subscribe for a database whose ModuleHost is absent: database created but no module published yet, host still initializing after publish, or the host not yet spawned when the subscribe arrives.
Common situations: Clients subscribing immediately after server start or publish before the module host is live; empty databases that never had a module; client libraries defaulting to the v2 subscription protocol against a database in that state.
Related errors
- cannot deserialize refs without a typespace
- length didn't fit in `u32`
- Deletion for non-existent table {table_id:?}... huh?
- Event tables cannot be used as the lookup table in subscript
- unable to decode args
AI-assisted analysis of clockworklabs/SpacetimeDB@9e0d92412f (2026-08-20).
Data as JSON: /api/errors/c2f0a436d88fa920.
Report an issue: GitHub.