{"record":{"id":"78f29fb015d0a020","repo":"clockworklabs/SpacetimeDB","slug":"error-enum-s-did-not-register-as-a-complex-typ","errorCode":null,"errorMessage":"ERROR: Enum '%s' did not register as a complex type\\n","messagePattern":"ERROR: Enum '(.+?)' did not register as a complex type\\\\n","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/bindings-cpp/src/internal/module_type_registration.cpp","lineNumber":198,"sourceCode":"                                                 const std::type_info* cpp_type) {\n    // Check if already registered in cache\n    auto cache_it = type_name_cache_.find(type_name);\n    if (cache_it != type_name_cache_.end()) {\n        return cache_it->second;\n    }\n    \n    // Register the type and get the Internal::AlgebraicType result\n    AlgebraicType result = registerType(bsatn_type, type_name, cpp_type);\n    \n    // If it's a Ref, return the index\n    if (result.get_tag() == AlgebraicType::Tag::Ref) {\n        uint32_t index = result.get<0>();\n        type_name_cache_[type_name] = index;\n        return index;\n    }\n    \n    // This shouldn't happen for enums - they should always register as complex types\n    fprintf(stderr, \"ERROR: Enum '%s' did not register as a complex type\\n\", type_name.c_str());\n    return 0;\n}\n\nvoid ModuleTypeRegistration::registerTypeByName(const std::string& type_name, \n                                            const bsatn::AlgebraicType& algebraic_type,\n                                            [[maybe_unused]] const std::type_info* cpp_type) {\n    // Check if already registered in cache\n    auto cache_it = type_name_cache_.find(type_name);\n    if (cache_it != type_name_cache_.end()) {\n        return;\n    }\n    \n    // Check if already registered in module's types array\n    for (const auto& type_def : getV10Builder().GetTypeDefs()) {\n        if (type_def.source_name.source_name == type_name) {\n            uint32_t typespace_index = type_def.ty;\n            type_name_cache_[type_name] = typespace_index;\n            return;","sourceCodeStart":180,"sourceCodeEnd":216,"githubUrl":"https://github.com/clockworklabs/SpacetimeDB/blob/6dee26c6efc2856793e12b148a59742964f5d783/crates/bindings-cpp/src/internal/module_type_registration.cpp#L180-L216","documentation":"Invariant violation in ModuleTypeRegistration::registerAndGetIndex: for an enum, registerType is expected to return a Ref (typespace index) but returned some other AlgebraicType tag. This happens when the registration path degenerates - e.g. an error state was already set (registerType returns a dummy U8), or the enum's bsatn type was not treated as a complex Sum type (missing/incorrect enum serialization annotation, or a name collision resolving to a primitive). Note the function then returns index 0, which silently aliases whatever type occupies typespace slot 0.","triggerScenarios":"Registering an enum while a previous registration error set has_error_ (dummy U8 returned instead of a Ref); an enum type whose bsatn representation is not a Sum because the enum macro/serialization support was not applied; an enum name that collides with an already-registered primitive or special type.","commonSituations":"Defining enums used as table columns without the proper SpacetimeDB enum macros for the toolchain; mixing manually-registered types (registerTypeByName) with enum registration using identical names; ignoring an earlier registration error and continuing to register enums.","solutions":["Check for earlier registration errors first - if hasError() is set the dummy type causes this; fix the original error","Ensure the enum uses the SpacetimeDB enum registration/serialization macro so its bsatn type is a proper Sum with named variants","Rename the enum if its name collides with a previously registered primitive, special, or identically named complex type","If it persists with a well-formed enum, capture the type name and report it as a bindings-cpp bug"],"exampleFix":"// before\nenum class Status { Ok, Err }; // no SpacetimeDB enum registration\n\n// after\n// use the provided enum registration so bsatn yields a Sum type\nSPACETIMEDB_ENUM(Status, Ok, Err);","handlingStrategy":"validation","validationCode":"// before registering enums, ensure no error state is pending\n// if (getModuleTypeRegistration().hasError()) { /* fix root cause first */ }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always apply the SpacetimeDB enum registration macro so bsatn yields a Sum type","Give enums unique names that cannot collide with primitives or special types","Fix earlier registration errors before registering more types - error state turns results into dummy types"],"tags":["spacetimedb","cpp","enum","types","registration"],"backgroundTag":"enum-type-registration-failed","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"}