clockworklabs/SpacetimeDB · critical · InvalidOperationException

Invalid HTTP handler signature.

Error message

Invalid HTTP handler signature.

What it means

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.

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 $$"""
            class {{Identifier}} : SpacetimeDB.Internal.IHttpHandler {
                public SpacetimeDB.Internal.RawHttpHandlerDefV10 MakeHandlerDef() => new(
                    SourceName: nameof({{Identifier}})
                );

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

View on GitHub (pinned to 524b4487d9)

Solutions

  1. Use the canonical shape: public static HttpResponse Name(HandlerContext ctx, HttpRequest request)
  2. Resolve the build-time diagnostic emitted for the malformed handler before shipping
  3. Fetch dependencies/services from the HandlerContext rather than extra parameters
  4. Smoke-test each route in a dev deployment so the throw surfaces in CI

Example fix

// before
public static HttpResponse GetPlayer(Microsoft.AspNetCore.Http.HttpContext ctx) { ... } // wrong signature

// after
public static HttpResponse GetPlayer(HandlerContext ctx, HttpRequest request) { ... }
Defensive patterns

Strategy: validation

Validate before calling

// CI gate: every HTTP handler method must be (HandlerContext, HttpRequest).
var bad = typeof(Module).GetMethods(BindingFlags.Public | BindingFlags.Static)
    .Where(m => m.GetCustomAttribute<HttpHandlerAttribute>() is not null)
    .Where(m =>
    {
        var p = m.GetParameters();
        return p.Length != 2 || p[0].ParameterType != typeof(SpacetimeDB.HandlerContext) || p[1].ParameterType != typeof(SpacetimeDB.HttpRequest);
    });
foreach (var m in bad) throw new InvalidOperationException($"Bad HTTP handler signature: {m.Name}");

Try / catch

// Dev smoke test per route so the generated throw fails fast:
try { handler.Invoke(testCtx, testRequest); }
catch (TargetInvocationException ex) when (ex.InnerException?.Message == "Invalid HTTP handler signature.") { Assert.Fail(ex.InnerException.Message); }

Prevention

When it happens

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

Common situations: Adapting middleware-style handlers that take HttpContext (ASP.NET muscle memory); SDK upgrades renaming context types; refactoring handlers to accept extra services via parameters.

Related errors

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