clockworklabs/SpacetimeDB · error

[CONSTRAINT REGISTRATION ERROR] Module cleared and replaced

Error message

[CONSTRAINT REGISTRATION ERROR] Module cleared and replaced with error type: %s

What it means

Banner printed by __preinit__99_validate_types when g_constraint_registration_error is set. The module is cleared and replaced by error type ERROR_CONSTRAINT_REGISTRATION_<code> (code sanitized to [A-Za-z0-9_]) at invalid typespace index 999999, so the server fails to resolve the module description; the banner names the generated error type so you can correlate it with the publish failure.

Source

Thrown at crates/bindings-cpp/src/internal/Module.cpp:286

    if (g_constraint_registration_error) {
        getV10Builder().Clear();

        std::string error_type_name = "ERROR_CONSTRAINT_REGISTRATION_" + g_constraint_registration_error_code;
        for (char& c : error_type_name) {
            if (!std::isalnum(c) && c != '_') {
                c = '_';
            }
        }

        RawTypeDefV10 error_type;
        error_type.source_name.scope = {};
        error_type.source_name.source_name = error_type_name;
        error_type.ty = 999999;
        error_type.custom_ordering = false;
        getV10Builder().GetTypeDefs().push_back(error_type);

        fprintf(stderr, "\n[CONSTRAINT REGISTRATION ERROR] Module cleared and replaced with error type: %s\n", error_type_name.c_str());
        fprintf(stderr, "Original error: %s\n\n", g_constraint_registration_error_details.c_str());
        fflush(stderr);
        return;
    }
    
    // Check if any errors occurred during type registration
    auto& type_reg = getModuleTypeRegistration();
    if (type_reg.hasError()) {
        // Type registration detected an error - create a special error module
        const std::string& error = type_reg.getErrorMessage();
        
        // Clear the module state to start fresh.
        getV10Builder().Clear();
        
        // Create an error type name that embeds the error message and type structure
        std::string error_type_name;
        if (error.find("Recursive type reference") != std::string::npos) {
            // Extract the type name from the error message

View on GitHub (pinned to 6dee26c6ef)

Solutions

1. Match the ERROR_CONSTRAINT_REGISTRATION_<code> name from this banner to the codes in v10_builder.h to identify the exact check that failed
2. Read the 'Original error:' line printed right after it (error 669) - it carries table/field/index names
3. Fix the named macro (field name typo, ordering, empty index list) and republish

Example fix

// before
INDEX_MULTI(MyTable, my_index, ); // empty field list -> MULTI_INDEX_EMPTY

// after
INDEX_MULTI(MyTable, my_index, owner_id, created_at);

When it happens

Trigger: Any SetConstraintRegistrationError code raised by V10Builder: FIELD_NOT_FOUND, TABLE_NOT_FOUND, NO_FIELD_DESCRIPTORS, TABLE_NO_FIELD_DESCRIPTORS, MULTI_INDEX_EMPTY, DEFAULT_ON_PRIMARY_KEY, duplicate constraint/index names, etc.

Common situations: Field renamed without updating constraint macros; constraint macros compiled before the table registration; empty multi-column index argument lists; schema refactors across translation units.

Related errors

• ERROR: Constraint registration failed [%s] %s
• [CONSTRAINT ERROR] Module cleared and replaced with error t
• Original error: %s
• table should exist in the database for AddConstraint
• ERROR: Multiple primary keys detected in table '%s'

AI-assisted analysis of clockworklabs/SpacetimeDB@6dee26c6ef (2026-08-20). Data as JSON: /api/errors/784adb77538341a3. Report an issue: GitHub.