{"record":{"id":"20283899e7070f5c","repo":"clockworklabs/SpacetimeDB","slug":"error-invalid-http-handler-id-u-have-zu-handle","errorCode":null,"errorMessage":"ERROR: Invalid http handler ID %u (have %zu handlers)\\n","messagePattern":"ERROR: Invalid http handler ID %u \\(have %zu handlers\\)\\\\n","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/bindings-cpp/src/internal/Module.cpp","lineNumber":639,"sourceCode":"    // Call the procedure handler - this may trap if there's an error\n    std::vector<uint8_t> result_data = handler_info.handler(ctx, args_source);\n    \n    // If we got here, procedure succeeded - write result\n    WriteBytes(result_sink, result_data);\n    \n    return 0;  // Success (StatusCode::OK)\n}\n\nint16_t Module::__call_http_handler__(\n    uint32_t id,\n    uint64_t timestamp_microseconds,\n    BytesSource request_source,\n    BytesSource request_body_source,\n    BytesSink response_sink,\n    BytesSink response_body_sink\n) {\n    if (id >= g_http_handlers.size()) {\n        fprintf(stderr, \"ERROR: Invalid http handler ID %u (have %zu handlers)\\n\",\n                id, g_http_handlers.size());\n        return -1;\n    }\n\n    Timestamp timestamp = Timestamp::from_micros_since_epoch(static_cast<int64_t>(timestamp_microseconds));\n    HandlerContext ctx(timestamp);\n\n    std::vector<uint8_t> request_bytes = ConsumeBytes(request_source);\n    bsatn::Reader request_reader(request_bytes.data(), request_bytes.size());\n    wire::HttpRequest wire_request = bsatn::deserialize<wire::HttpRequest>(request_reader);\n    HttpRequest request = convert::from_wire(wire_request, ConsumeBytes(request_body_source));\n\n    HttpResponse response = g_http_handlers[id].handler(ctx, std::move(request));\n    auto [wire_response, response_body] = convert::to_wire_split(response);\n\n    std::vector<uint8_t> response_metadata;\n    {\n        bsatn::Writer writer(response_metadata);","sourceCodeStart":621,"sourceCodeEnd":657,"githubUrl":"https://github.com/clockworklabs/SpacetimeDB/blob/6dee26c6efc2856793e12b148a59742964f5d783/crates/bindings-cpp/src/internal/Module.cpp#L621-L657","documentation":"Dispatch guard in Module::__call_http_handler__: the host invoked an HTTP handler by numeric ID >= g_http_handlers.size(). The function logs the message and returns -1, failing the HTTP request. The http-handler table registered at module init is smaller than the IDs the server dispatches, i.e. binary and published module description disagree.","triggerScenarios":"HTTP handler registration (RegisterHttpHandlerHandler) skipped for some handlers because of conditional compilation or a partially failed preinit; stale module binary served against newer metadata; handler/router macros reordered so fewer handlers register.","commonSituations":"Iterating on the unstable HTTP feature and republishing while the server caches the previous handler table; feature-flag builds that exclude some handlers.","solutions":["Republish the module so the HTTP handler table matches what the server dispatches","Register every HTTP handler unconditionally; keep handler macros ahead of router references (see error 663)","Check server logs for module init errors that could have skipped handler registration","Retest with a fresh HTTP request after republish - cached routing metadata can also live server-side"],"exampleFix":"// before\nHTTP_HANDLER(get_user);\n#ifdef ADMIN\nHTTP_HANDLER(admin_panel); // sometimes absent -> id mismatch\n#endif\n\n// after\nHTTP_HANDLER(get_user);\nHTTP_HANDLER(admin_panel); // always registered","handlingStrategy":"validation","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep HTTP handler macros unconditional and ordered before router references","Republish after changing the handler set so server-side routing metadata refreshes","Smoke-test one request per route after publish"],"tags":["spacetimedb","cpp","http","dispatch","module-version-mismatch"],"backgroundTag":"no-such-http-handler","analyzedSha":"6dee26c6efc2856793e12b148a59742964f5d783","analyzedAt":"2026-08-20T06:08:37.179Z","contentChangedAt":"2026-08-20T06:08:37.179Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}