{"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":"critical","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            class {{Identifier}} : SpacetimeDB.Internal.IHttpHandler {\n                public SpacetimeDB.Internal.RawHttpHandlerDefV10 MakeHandlerDef() => new(\n                    SourceName: nameof({{Identifier}})\n                );\n\n                public 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/524b4487d949b61a07d4f39c862d1290259dfd20/crates/bindings-csharp/Codegen/Module.cs#L1920-L1956","documentation":"Generated HTTP handler classes route incoming requests through Invoke; when the annotated method's signature does not match the expected HTTP handler shape, the generator emits an Invoke that throws InvalidOperationException(\"Invalid HTTP handler signature.\") on the first request. The generator also warns about reserved name prefixes (__, on, On) separately.","triggerScenarios":"Declaring the handler without (HandlerContext ctx, HttpRequest request), changing the request/context parameter types, making it instance-level or private, or returning something other than the expected response type.","commonSituations":"Adapting middleware-style handlers that take HttpContext (ASP.NET muscle memory); SDK upgrades renaming context types; refactoring handlers to accept extra services via parameters.","solutions":["Use the canonical shape: public static HttpResponse Name(HandlerContext ctx, HttpRequest request)","Resolve the build-time diagnostic emitted for the malformed handler before shipping","Fetch dependencies/services from the HandlerContext rather than extra parameters","Smoke-test each route in a dev deployment so the throw surfaces in CI"],"exampleFix":"// before\npublic static HttpResponse GetPlayer(Microsoft.AspNetCore.Http.HttpContext ctx) { ... } // wrong signature\n\n// after\npublic static HttpResponse GetPlayer(HandlerContext ctx, HttpRequest request) { ... }","handlingStrategy":"validation","validationCode":"// CI gate: every HTTP handler method must be (HandlerContext, HttpRequest).\nvar bad = typeof(Module).GetMethods(BindingFlags.Public | BindingFlags.Static)\n    .Where(m => m.GetCustomAttribute<HttpHandlerAttribute>() is not null)\n    .Where(m =>\n    {\n        var p = m.GetParameters();\n        return p.Length != 2 || p[0].ParameterType != typeof(SpacetimeDB.HandlerContext) || p[1].ParameterType != typeof(SpacetimeDB.HttpRequest);\n    });\nforeach (var m in bad) throw new InvalidOperationException($\"Bad HTTP handler signature: {m.Name}\");","typeGuard":null,"tryCatchPattern":"// Dev smoke test per route so the generated throw fails fast:\ntry { handler.Invoke(testCtx, testRequest); }\ncatch (TargetInvocationException ex) when (ex.InnerException?.Message == \"Invalid HTTP handler signature.\") { Assert.Fail(ex.InnerException.Message); }","preventionTips":["Use the exact (HandlerContext ctx, HttpRequest request) shape for every handler","Avoid reserved name prefixes (__, on, On) for handlers","Smoke-test every route in a dev deployment before release"],"tags":["csharp","codegen","http-handler","source-generator","spacetimedb"],"backgroundTag":"handler-signature-invalid","analyzedSha":"524b4487d949b61a07d4f39c862d1290259dfd20","analyzedAt":"2026-08-16T23:58:54.611Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}