{"record":{"id":"4cc6a6dd009fa827","repo":"clockworklabs/SpacetimeDB","slug":"invalid-http-handler-signature","errorCode":null,"errorMessage":"Invalid HTTP handler signature.","messagePattern":"Invalid HTTP handler signature\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"crates/bindings-csharp/Codegen/Module.cs","lineNumber":1938,"sourceCode":"        }\n\n        Name = method.Name;\n        if (Name.Length >= 2)\n        {\n            var prefix = Name[..2];\n            if (prefix is \"__\" or \"on\" or \"On\")\n            {\n                diag.Report(ErrorDescriptor.HttpHandlerReservedPrefix, (methodSyntax, prefix));\n            }\n        }\n\n        FullName = SymbolToName(method);\n    }\n\n    public string GenerateClass()\n    {\n        var body = HasWrongSignature\n            ? \"throw new System.InvalidOperationException(\\\"Invalid HTTP handler signature.\\\");\"\n            : $\"return {FullName}((SpacetimeDB.HandlerContext)ctx, request);\";\n\n        return $$\"\"\"\n            sealed class {{Identifier}} : SpacetimeDB.Internal.IHttpHandler {\n                public SpacetimeDB.Internal.RawHttpHandlerDefV10 MakeHandlerDef() => new(\n                    SourceName: nameof({{Identifier}})\n                );\n\n                public static SpacetimeDB.HttpResponse Invoke(\n                    SpacetimeDB.HandlerContextBase ctx,\n                    SpacetimeDB.HttpRequest request\n                ) {\n                    {{body}}\n                }\n            }\n            \"\"\";\n    }\n}","sourceCodeStart":1920,"sourceCodeEnd":1956,"githubUrl":"https://github.com/clockworklabs/SpacetimeDB/blob/eddf9f5014579a50d4b67630e28b6e15cad9c4af/crates/bindings-csharp/Codegen/Module.cs#L1920-L1956","documentation":"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.\").","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use the exact fixed shape: `public static HttpResponse MyHandler(HandlerContext ctx, HttpRequest request)`","Remove type parameters, extra/missing parameters, and async modifiers from the handler","Resolve any naming collision so `HandlerContext`/`HttpRequest`/`HttpResponse` bind to the SpacetimeDB namespace types","Make STDB HttpHandlerSignature/ContextParam/RequestParam/ReturnType diagnostics build errors, then rebuild and republish"],"exampleFix":"// before\n[SpacetimeDB.HttpHandler]\npublic static HttpResponse Health(object ctx, HttpRequest req) => new(200); // ctx type wrong\n\n// after\n[SpacetimeDB.HttpHandler]\npublic static HttpResponse Health(HandlerContext ctx, HttpRequest request) => new(200);","handlingStrategy":"validation","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":["Fix the handler shape exactly: (HandlerContext ctx, HttpRequest request) => HttpResponse, non-generic, two parameters","Avoid name collisions: don't define your own HandlerContext/HttpRequest types in the module namespace","Don't port ASP.NET handler signatures verbatim — no HttpContext, no async Task returns"],"tags":["csharp","http-handler","code-generation","spacetimedb-module","signature"],"backgroundTag":"generated-code-invalid-signature","analyzedSha":"eddf9f5014579a50d4b67630e28b6e15cad9c4af","analyzedAt":"2026-08-20T06:08:37.179Z","contentChangedAt":"2026-08-20T06:08:37.179Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}