{"record":{"id":"280c676de108ddac","repo":"clockworklabs/SpacetimeDB","slug":"error-failed-to-register-named-complex-type-s","errorCode":null,"errorMessage":"ERROR: Failed to register named complex type '%s'\\n","messagePattern":"ERROR: Failed to register named complex type '(.+?)'\\\\n","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"crates/bindings-cpp/src/internal/module_type_registration.cpp","lineNumber":224,"sourceCode":"    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;\n        }\n    }\n\n    // Register by name using the same full-fidelity path as other complex type registration.\n    // This avoids lossy conversion of nested fields/variants.\n    auto result = registerType(algebraic_type, type_name, cpp_type);\n    if (result.get_tag() != AlgebraicType::Tag::Ref) {\n        fprintf(stderr, \"ERROR: Failed to register named complex type '%s'\\n\", type_name.c_str());\n    }\n}\n\nbool ModuleTypeRegistration::isPrimitive(const bsatn::AlgebraicType& type) const {\n    auto tag = static_cast<uint32_t>(type.tag());\n    // Use range check: String (4) to F64 (19) covers all primitive types\n    return tag >= static_cast<uint32_t>(bsatn::AlgebraicTypeTag::String) &&\n           tag <= static_cast<uint32_t>(bsatn::AlgebraicTypeTag::F64);\n}\n\nbool ModuleTypeRegistration::isSpecialType(const bsatn::AlgebraicType& type) const {\n    if (type.tag() != bsatn::AlgebraicTypeTag::Product) {\n        return false;\n    }\n    \n    const auto& product = type.as_product();\n    if (product.elements.size() != 1) {\n        return false;","sourceCodeStart":206,"sourceCodeEnd":242,"githubUrl":"https://github.com/clockworklabs/SpacetimeDB/blob/6dee26c6efc2856793e12b148a59742964f5d783/crates/bindings-cpp/src/internal/module_type_registration.cpp#L206-L242","documentation":"Warning-level failure log in ModuleTypeRegistration::registerTypeByName: after checking the cache and the module's existing type defs, it registers the named complex type via registerType and expects a Ref back; a non-Ref result means the type did not land in the typespace as a named complex type. Unlike the enum path it does not corrupt an index, but the type is missing from the module description, which can surface later as unresolved types or schema mismatches on the server.","triggerScenarios":"registerTypeByName called (e.g. from V10Builder::RegisterTable for Sum-typed fields) while an earlier error state is active (dummy U8 returned); the supplied algebraic_type resolves to a primitive or special type (Identity/ConnectionId-shaped products) instead of a complex type; the name is already cached under a different shape.","commonSituations":"Naming a table's sum-type field identically to a built-in/special type; registering nested variant types while a prior registration already failed; version changes in bindings-cpp altering which types count as 'special'.","solutions":["Rename the type so it cannot collide with built-in/special type names (Identity, ConnectionId, ScheduleAt spellings)","Check for and fix any earlier registration error - the has_error_ state makes registerType return non-Ref","Ensure the algebraic type passed in is genuinely a complex type (Sum/Product), not one that isPrimitive()/isSpecialType() filters out","Verify the module description after publish contains the named type; if not, restructure the field type (e.g. introduce a dedicated struct)"],"exampleFix":"// before: field type name collides with a special type name\nstruct Event { Identity Identity; }; // named like the special type\n\n// after\nstruct Event { Identity sender; }; // distinct field/type naming","handlingStrategy":"validation","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":["Avoid naming user types after built-in/special types (Identity, ConnectionId, ScheduleAt)","Check hasError() after bulk type registration and fix the first failure before continuing","Verify published module descriptions contain every named type you register"],"tags":["spacetimedb","cpp","types","registration","naming"],"backgroundTag":"type-registration-failed","analyzedSha":"6dee26c6efc2856793e12b148a59742964f5d783","analyzedAt":"2026-08-20T06:08:37.179Z","contentChangedAt":"2026-08-20T06:08:37.179Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}