clockworklabs/SpacetimeDB · error · InvalidOperationException

Invalid HTTP handler signature.

Error message

Invalid HTTP handler signature.

What it means

Runtime throw from the generated stub for an [HttpHandler] method. HttpHandlerDeclaration arms HasWrongSignature for any of: method has generics or != 2 parameters, first parameter is not SpacetimeDB.HandlerContext (checked both semantically and syntactically to allow the unqualified identifier), second parameter is not exactly SpacetimeDB.HttpRequest, or the return type is not exactly SpacetimeDB.HttpResponse (Module.cs:1861-1919). The generated IHttpHandler.Invoke then always throws InvalidOperationException("Invalid HTTP handler signature.").

Solutions

1. Use the exact fixed shape: `public static HttpResponse MyHandler(HandlerContext ctx, HttpRequest request)`
2. Remove type parameters, extra/missing parameters, and async modifiers from the handler
3. Resolve any naming collision so `HandlerContext`/`HttpRequest`/`HttpResponse` bind to the SpacetimeDB namespace types
4. Make STDB HttpHandlerSignature/ContextParam/RequestParam/ReturnType diagnostics build errors, then rebuild and republish

Example fix

// before
[SpacetimeDB.HttpHandler]
public static HttpResponse Health(object ctx, HttpRequest req) => new(200); // ctx type wrong

// after
[SpacetimeDB.HttpHandler]
public static HttpResponse Health(HandlerContext ctx, HttpRequest request) => new(200);

When it happens

Trigger: Declaring a handler with the wrong context type (e.g. `object ctx`, `HandlerContext<T>`, or a custom alias), wrong parameter count (1 or 3 params), a generic method, a second parameter that is not SpacetimeDB.HttpRequest, or returning Task/string/void instead of SpacetimeDB.HttpResponse — then publishing despite the HttpHandler* diagnostics and receiving a request.

Common situations: Porting ASP.NET-core style handlers (HttpContext, Task< IActionResult >) to SpacetimeDB; defining a local HandlerContext class that shadows SpacetimeDB.HandlerContext; async-style signatures; using a request DTO instead of the fixed HttpRequest wire type.

Related errors

• Invalid procedure signature.
• InvalidTableVisibility
• Transaction context was not initialised.
• Unique index point scan returned >1 rows
• Argument must be a ConnectionId

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

Appendix: source

Thrown at crates/bindings-csharp/Codegen/Module.cs:1938

        }

        Name = method.Name;
        if (Name.Length >= 2)
        {
            var prefix = Name[..2];
            if (prefix is "__" or "on" or "On")
            {
                diag.Report(ErrorDescriptor.HttpHandlerReservedPrefix, (methodSyntax, prefix));
            }
        }

        FullName = SymbolToName(method);
    }

    public string GenerateClass()
    {
        var body = HasWrongSignature
            ? "throw new System.InvalidOperationException(\"Invalid HTTP handler signature.\");"
            : $"return {FullName}((SpacetimeDB.HandlerContext)ctx, request);";

        return $$"""
            sealed class {{Identifier}} : SpacetimeDB.Internal.IHttpHandler {
                public SpacetimeDB.Internal.RawHttpHandlerDefV10 MakeHandlerDef() => new(
                    SourceName: nameof({{Identifier}})
                );

                public static SpacetimeDB.HttpResponse Invoke(
                    SpacetimeDB.HandlerContextBase ctx,
                    SpacetimeDB.HttpRequest request
                ) {
                    {{body}}
                }
            }
            """;
    }
}

View on GitHub (pinned to eddf9f5014)