clockworklabs/SpacetimeDB · error

Original error: %s

Error message

Original error: %s

What it means

Detail line of the '[CONSTRAINT REGISTRATION ERROR]' banner (error 668) that prints g_constraint_registration_error_details - the human-readable description recorded when SetConstraintRegistrationError was called. It typically names the table, field, or index involved, e.g. "table='User' field='usr_id' was not found".

Source

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

    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
            size_t start = error.find("'");

View on GitHub (pinned to 6dee26c6ef)

Solutions

1. Parse the table='X' field='Y' (or index='Z') tokens in this line to locate the offending macro
2. Correct the macro: fix the field name, register the table first, or populate the index column list
3. Republish and verify the constraint error type is gone from the module description

Example fix

// before: details say field='usr_id' was not found
FIELD_Unique(User, usr_id);

// after
FIELD_Unique(User, user_id);

When it happens

Trigger: Always printed after error 668's banner; the details string comes directly from whichever V10Builder constraint check failed (field not found, table not registered, empty multi-index, default on primary key, and similar).

Common situations: Debugging a failed publish where the server only reports an ERROR_CONSTRAINT_REGISTRATION_* type; this stderr line is the only place the concrete table/field names appear.

Related errors

• ERROR: Constraint registration failed [%s] %s
• Original error: Multiple primary keys detected in table '%s'
• [CONSTRAINT REGISTRATION ERROR] Module cleared and replaced
• 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/0ea5f8954d57410d. Report an issue: GitHub.