clockworklabs/SpacetimeDB · error · InvalidOperationException

Unrecognized extra bytes while decoding BSATN value

Error message

Unrecognized extra bytes while decoding BSATN value

What it means

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.

Source

Thrown at crates/bindings-csharp/Runtime/Http.cs:391

                    );
            }
        }
        // Important: avoid throwing across the procedure boundary.
        // Throwing here would trap the module (and fail the whole procedure invocation).
        // Convert all unexpected failures (including decode errors / unexpected errno) into Result.Err instead.
        catch (Exception ex)
        {
            return Result<HttpResponse, HttpError>.Err(new HttpError(ex.ToString()));
        }
    }

    private static T FromBytes<T>(IReadWrite<T> rw, MemoryStream ms)
    {
        using var reader = new BinaryReader(ms);
        var value = rw.Read(reader);
        if (ms.Position != ms.Length)
        {
            throw new InvalidOperationException(
                "Unrecognized extra bytes while decoding BSATN value"
            );
        }
        return value;
    }

    private static HttpMethodWire ToWireMethod(HttpMethod method)
    {
        var m = method.Value;
        return m switch
        {
            "GET" => new HttpMethodWire.Get(default),
            "HEAD" => new HttpMethodWire.Head(default),
            "POST" => new HttpMethodWire.Post(default),
            "PUT" => new HttpMethodWire.Put(default),
            "DELETE" => new HttpMethodWire.Delete(default),
            "CONNECT" => new HttpMethodWire.Connect(default),
            "OPTIONS" => new HttpMethodWire.Options(default),

View on GitHub (pinned to 524b4487d9)

Solutions

1. Align versions: pin the C# SDK NuGet to the version matching your SpacetimeDB host/CLI per the compatibility matrix
2. Rebuild and republish the module after upgrading either side
3. Check HttpError.ToString() in the Result.Err path - this message indicates protocol skew, not a bad request
4. If versions match exactly and it persists, capture host + SDK versions and file a SpacetimeDB issue

// Not validatable client-side: the host produces the bytes. Guard by asserting version
// alignment at module startup instead.
if (!SdkVersion.IsCompatibleWithHost) throw new InvalidOperationException($"SDK {SdkVersion.Current} not compatible with host {SdkVersion.Host}");

// HttpRequest already returns Result<HttpResponse, HttpError>; pattern-match and degrade gracefully:
var result = http.Send(request);
return result.Match<HttpResponse?>(
    onOk: resp => resp,
    onErr: err when err.ToString().Contains("extra bytes") => null, // protocol skew: fail soft, alert ops
    onErr: err => throw new InvalidOperationException(err.ToString()));

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Invalid HTTP method returned from host
• Invalid HTTP version returned from host
• Error while reading {typeof(T).FullName}: expected source sp
• HTTP router references unknown handler `{route.HandlerFuncti
• Index '${idx.sourceName ?? '<unknown>'}' on table '${tableDe

AI-assisted analysis of clockworklabs/SpacetimeDB@524b4487d9 (2026-08-16). Data as JSON: /api/errors/dd86a879b1730c75. Report an issue: GitHub.