[CIRCULAR REFERENCE ERROR] Module cleared and replaced with

Error message

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

What it means

Banner printed by __preinit__99_validate_types when the global g_circular_ref_error flag was set while building the module typespace. The entire module is cleared and replaced by a single error type named ERROR_CIRCULAR_REFERENCE_<type> pointing at invalid typespace index 999999, which makes the server fail module description resolution; this stderr banner is the module-side diagnostic for that publish failure.

Source

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

        
        // Create the error type name that indicates the circular reference
        std::string error_type_name = "ERROR_CIRCULAR_REFERENCE_" + g_circular_ref_type_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[CIRCULAR REFERENCE ERROR] Module cleared and replaced with error type: %s\n", error_type_name.c_str());
        fprintf(stderr, "  Type '%s' contains a circular reference to itself\n", g_circular_ref_type_name.c_str());
        fflush(stderr);
        return; // Exit early, don't check other errors
    }
    
    // Check if multiple primary key error occurred during constraint registration
    if (g_multiple_primary_key_error) {
        // Multiple primary key error detected - create a special error module
        
        // Clear the module state to start fresh.
        getV10Builder().Clear();
        
        // 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;

View on GitHub (pinned to 6dee26c6ef)

Solutions

Locate the type named in the banner and break the cycle: replace self-referencing members with row-id references (uint64_t foreign keys into another table)
Use supported indirection (Box/unique_ptr-style wrapper) for recursive structure if the bindings version supports it
Hoist the recursive payload into its own table and reference it by id from both sides

Example fix

// before
struct Node {
  std::string label;
  std::vector<Node> children; // re-enters registration for 'Node'
};

// after
struct Node {
  std::string label;
  std::vector<uint64_t> child_ids; // reference rows by id
};

Defensive patterns

Strategy: validation

Validate before calling

// host-side smoke test: run module init and inspect the description
// (call __describe_module__ in a test harness) and assert no error types
// for (auto& td : typeDefs)
//   assert(td.source_name.source_name.rfind("ERROR_", 0) != 0);

Prevention

Model recursive structures as rows plus id references, not nested value types
Review new table columns for types that transitively contain themselves
Run a describe-module smoke test in CI to catch ERROR_CIRCULAR_REFERENCE_* types before deploy

When it happens

Trigger: A type registered in a table/reducer/view references itself through the registration machinery - e.g. struct A containing std::vector<A> members whose field types re-enter registerType for the same type name while it is still being registered; mutual recursion A -> B -> A across table column types.

Common situations: Modeling graphs, trees or linked lists as nested value types instead of table rows; porting C++ domain types unchanged and marking them as table columns.

Related errors

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