clockworklabs/SpacetimeDB · error

[CONSTRAINT ERROR] Module cleared and replaced with error t

Error message

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

What it means

Banner printed by __preinit__99_validate_types when g_multiple_primary_key_error was set during constraint registration. The module is cleared and replaced with the single error type ERROR_MULTIPLE_PRIMARY_KEYS_<table> at invalid typespace index 999999, so the server rejects the module description and the publish fails; this banner is the module-side explanation.

Source

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

        
        // Create the error type name
        std::string error_type_name = "ERROR_MULTIPLE_PRIMARY_KEYS_" + g_multiple_primary_key_table_name;
        
        // Add a single named type export that points to a non-existent typespace index
        // This will cause SpacetimeDB to error when it tries to resolve the type
        RawTypeDefV10 error_type;
        error_type.source_name.scope = {};
        error_type.source_name.source_name = error_type_name;
        error_type.ty = 999999; // Invalid typespace index - will cause an error
        error_type.custom_ordering = false;
        
        getV10Builder().GetTypeDefs().push_back(error_type);
        
        // Don't add anything to the typespace - this ensures the reference is invalid
        // The server will fail with an error message that includes our error type name
        
        // Also log to stderr for debugging
        fprintf(stderr, "\n[CONSTRAINT ERROR] Module cleared and replaced with error type: %s\n", error_type_name.c_str());
        fprintf(stderr, "Original error: Multiple primary keys detected in table '%s'\n\n", g_multiple_primary_key_table_name.c_str());
        fflush(stderr);
        
        return; // Exit early, don't check type registration errors
    }

    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 = {};

View on GitHub (pinned to 6dee26c6ef)

Solutions

1. Find the table named ERROR_MULTIPLE_PRIMARY_KEYS_<table> in the banner and remove all but one primary-key macro on it
2. Express additional uniqueness with FIELD_Unique or a multi-column index instead
3. Grep every translation unit for FIELD_PrimaryKey and FIELD_PrimaryKeyAutoInc mentioning that table name

Example fix

// before
FIELD_PrimaryKey(Order, order_id);
FIELD_PrimaryKeyAutoInc(Order, customer_id); // second PK

// after
FIELD_PrimaryKey(Order, order_id);
FIELD_Unique(Order, customer_id);

When it happens

Trigger: Same condition as the 'Multiple primary keys detected' message (error 661): a second FIELD_PrimaryKey/FIELD_PrimaryKeyAutoInc constraint applied to a table that already has a primary-key column, detected in AddFieldConstraint.

Common situations: Composite-key SQL schemas ported verbatim; duplicated primary-key macros after copy-paste; constraints spread across multiple translation units so the clash is not obvious in one file.

Related errors

• ERROR: Multiple primary keys detected in table '%s'
• Original error: Multiple primary keys detected in table '%s'
• [CONSTRAINT REGISTRATION ERROR] Module cleared and replaced
• View '${exportName}' can have at most one primaryKey() colum
• When replaying `st_column` update: `table_primary_key` shoul

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