clockworklabs/SpacetimeDB · error · InvalidOperationException

Unrecognized extra bytes while decoding BSATN value

Error message

Unrecognized extra bytes while decoding BSATN value

What it means

Thrown by the module-side HTTP client (Runtime/Http.cs) when converting a host response payload into a typed value: FromBytes runs rw.Read(reader) over the response MemoryStream and then requires ms.Position == ms.Length. Leftover bytes mean the BSATN payload on the wire contains more data than the type's decoder consumed — the payload was encoded with a different (usually newer) schema than the bindings decoding it.

Solutions

1. Align versions: update the SpacetimeDB bindings packages and the spacetimedb host to matching releases
2. Verify the type passed to the HTTP receive API is exactly the type the endpoint serializes (no extra/missing fields)
3. Capture the raw response bytes and compare length vs. consumed bytes to identify the trailing data
4. If a proxy is involved, confirm it does not append to or re-chunk the body

// The HTTP helpers already wrap failures as Result<HttpResponse, HttpError>;
// pattern-match the Err side instead of letting FromBytes' throw escape:
var result = await SendRequest(...);
if (result is Result<HttpResponse, HttpError>.ErrR(var httpError))
{
    // httpError includes the decode failure; treat trailing-byte errors as
    // protocol corruption: reconnect or surface, never retry the same bytes
}

When it happens

Trigger: Host (spacetimedb / upstream HTTP service) returns a response body serialized with a schema that has extra trailing fields relative to the T used in FromBytes<T>; version skew between the module's SpacetimeDB bindings and the host's wire format; a proxy or middleware appending bytes to the response body.

Common situations: Upgrading spacetimedb server but not the SpacetimeDB.BSATN/Runtime packages (or vice versa); custom response types in the HTTP helpers that drift from the actual endpoint's payload; response bodies that are not pure BSATN (e.g. concatenated frames).

Related errors

• Invalid tag value, this state should be unreachable.
• Operation is not valid due to the current state of the…
• Tag is out of range of enum
• Unrecognised extra bytes in the
• Argument must be a I128

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

Appendix: 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 6dee26c6ef)