{"record":{"id":"0896ffea126a3c19","repo":"clockworklabs/SpacetimeDB","slug":"v2-subscriptions-require-binary-protocol","errorCode":null,"errorMessage":"v2 subscriptions require binary protocol","messagePattern":"v2 subscriptions require binary protocol","errorType":"exception","errorClass":"DBError::Other","httpStatus":null,"severity":"error","filePath":"crates/core/src/subscription/module_subscription_actor.rs","lineNumber":1410,"sourceCode":"            self.remove_failed_subscription(subscription_metrics, sender.id, failed_subscription)?;\n            send_err_msg(err.to_string().into());\n            return Ok((None, trapped));\n        }\n\n        let Ok((update, metrics)) = self.evaluate_queries(sender.clone(), &queries, &tx, TableUpdateType::Subscribe)\n        else {\n            self.remove_failed_subscription(subscription_metrics, sender.id, failed_subscription)?;\n            send_err_msg(\"Internal error evaluating queries\".into());\n            return Ok((None, trapped));\n        };\n        tx.metrics.merge(metrics);\n\n        subscription_metrics.num_queries_evaluated.inc_by(queries.len() as _);\n\n        let ws_v2::QueryRows { tables } = match update {\n            ws_v1::FormatSwitch::Bsatn(update) => query_rows_from_update(update, false)?,\n            ws_v1::FormatSwitch::Json(_) => {\n                return Err(DBError::Other(anyhow::anyhow!(\n                    \"v2 subscriptions require binary protocol\"\n                )))\n            }\n        };\n\n        let _ = self.broadcast_queue.send_client_message_v2(\n            sender.clone(),\n            Some(tx_offset),\n            ws_v2::SubscribeApplied {\n                request_id: request.request_id,\n                query_set_id: request.query_set_id,\n                rows: ws_v2::QueryRows { tables },\n            },\n        );\n\n        Ok((Some(metrics), trapped))\n    }\n    fn add_multi_subscription_inner<I: WasmInstance>(","sourceCodeStart":1392,"sourceCodeEnd":1428,"githubUrl":"https://github.com/clockworklabs/SpacetimeDB/blob/9e0d92412ff2248f401a8ad12d535f2b5ac30912/crates/core/src/subscription/module_subscription_actor.rs#L1392-L1428","documentation":"On the v2 subscribe path, the initial evaluation of the subscribed queries must produce BSATN updates so they can be converted into ws_v2::QueryRows for SubscribeApplied. evaluate_queries returned FormatSwitch::Json instead, so the rows cannot be shipped to a v2 client and the subscribe fails with this error.","triggerScenarios":"A v2 (binary protocol) client subscribing when the subscription actor evaluates queries under the JSON format - format mismatch between the negotiated protocol and evaluation settings.","commonSituations":"Version skew between client and server; servers without v2 support serving v2 clients; forced format settings in custom builds.","solutions":["Upgrade both client and server to matched versions with v2 binary protocol support","Verify the client connects with the v2 protocol so BSATN is used end-to-end","In custom builds, ensure BSATN (not JSON) is selected for v2 subscription evaluation"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Client-side guard: only use v2 subscribe when the connection negotiated binary\nif !connection.negotiated_v2_binary() {\n    return Err(anyhow::anyhow!(\"v2 subscribe requires a server and client with matching binary protocol support\"));\n}","typeGuard":null,"tryCatchPattern":"match subscribe_result {\n    Err(e) if e.to_string().contains(\"v2 subscriptions require binary protocol\") => {\n        // Fall back to the v1 protocol or upgrade the server, then resubscribe\n    }\n    other => other,\n}","preventionTips":["Verify server version supports v2 before opting into v2 clients","Keep protocol selection explicit in client configuration","Add a connection-time capability check in SDK wrappers"],"tags":["spacetimedb","subscriptions","subscribe","v2-protocol","bsatn"],"backgroundTag":"protocol-format-mismatch","analyzedSha":"9e0d92412ff2248f401a8ad12d535f2b5ac30912","analyzedAt":"2026-08-20T06:08:37.179Z","contentChangedAt":"2026-08-20T06:08:37.179Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}