{"record":{"id":"dd86a879b1730c75","repo":"clockworklabs/SpacetimeDB","slug":"unrecognized-extra-bytes-while-decoding-bsatn-valu","errorCode":null,"errorMessage":"Unrecognized extra bytes while decoding BSATN value","messagePattern":"Unrecognized extra bytes while decoding BSATN value","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"crates/bindings-csharp/Runtime/Http.cs","lineNumber":391,"sourceCode":"                    );\n            }\n        }\n        // Important: avoid throwing across the procedure boundary.\n        // Throwing here would trap the module (and fail the whole procedure invocation).\n        // Convert all unexpected failures (including decode errors / unexpected errno) into Result.Err instead.\n        catch (Exception ex)\n        {\n            return Result<HttpResponse, HttpError>.Err(new HttpError(ex.ToString()));\n        }\n    }\n\n    private static T FromBytes<T>(IReadWrite<T> rw, MemoryStream ms)\n    {\n        using var reader = new BinaryReader(ms);\n        var value = rw.Read(reader);\n        if (ms.Position != ms.Length)\n        {\n            throw new InvalidOperationException(\n                \"Unrecognized extra bytes while decoding BSATN value\"\n            );\n        }\n        return value;\n    }\n\n    private static HttpMethodWire ToWireMethod(HttpMethod method)\n    {\n        var m = method.Value;\n        return m switch\n        {\n            \"GET\" => new HttpMethodWire.Get(default),\n            \"HEAD\" => new HttpMethodWire.Head(default),\n            \"POST\" => new HttpMethodWire.Post(default),\n            \"PUT\" => new HttpMethodWire.Put(default),\n            \"DELETE\" => new HttpMethodWire.Delete(default),\n            \"CONNECT\" => new HttpMethodWire.Connect(default),\n            \"OPTIONS\" => new HttpMethodWire.Options(default),","sourceCodeStart":373,"sourceCodeEnd":409,"githubUrl":"https://github.com/clockworklabs/SpacetimeDB/blob/524b4487d949b61a07d4f39c862d1290259dfd20/crates/bindings-csharp/Runtime/Http.cs#L373-L409","documentation":"After the FFI call procedure_http_request returns, the SDK decodes the host's reply buffer as an HttpResponseWire BSATN value and asserts the buffer was fully consumed. Leftover trailing bytes mean the bytes were produced under a different BSATN schema than the SDK expects - in practice, a version mismatch between the SpacetimeDB module SDK and the host. The failure is caught and surfaced as Result.Err(HttpError) so it does not trap the module.","triggerScenarios":"Module compiled against an SDK NuGet version whose HTTP wire types (HttpResponseWire and friends) differ from the host's - e.g., a host update added fields to the wire struct; mixing preview/beta versions between CLI, host, and SDK.","commonSituations":"Upgrading spacetimedb server/CLI but not the C# SDK package (or vice versa); deploying a module built months ago against an upgraded host; CI rebuilding with floating SDK versions.","solutions":["Align versions: pin the C# SDK NuGet to the version matching your SpacetimeDB host/CLI per the compatibility matrix","Rebuild and republish the module after upgrading either side","Check HttpError.ToString() in the Result.Err path - this message indicates protocol skew, not a bad request","If versions match exactly and it persists, capture host + SDK versions and file a SpacetimeDB issue"],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"// Not validatable client-side: the host produces the bytes. Guard by asserting version\n// alignment at module startup instead.\nif (!SdkVersion.IsCompatibleWithHost) throw new InvalidOperationException($\"SDK {SdkVersion.Current} not compatible with host {SdkVersion.Host}\");","typeGuard":null,"tryCatchPattern":"// HttpRequest already returns Result<HttpResponse, HttpError>; pattern-match and degrade gracefully:\nvar result = http.Send(request);\nreturn result.Match<HttpResponse?>(\n    onOk: resp => resp,\n    onErr: err when err.ToString().Contains(\"extra bytes\") => null, // protocol skew: fail soft, alert ops\n    onErr: err => throw new InvalidOperationException(err.ToString()));","preventionTips":["Pin the SDK NuGet version to the host version and update them together","Include SDK + host versions in module logs at startup to make skew diagnosable","Never retry on this error - redeploy the module instead"],"tags":["csharp","http","bsatn","ffi","version-mismatch","spacetimedb"],"backgroundTag":"wire-protocol-version-mismatch","analyzedSha":"524b4487d949b61a07d4f39c862d1290259dfd20","analyzedAt":"2026-08-16T23:58:54.611Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}