clockworklabs/SpacetimeDB · error

Local module schema validation failed

Error message

Local module schema validation failed

What it means

Once the inspector's JSON parses into RawModuleDef, ModuleDef::try_from performs semantic validation (table/index/reducer definitions). If conversion fails, the schema is structurally valid JSON but semantically invalid, and this error is returned — intentionally without echoing schema literals.

Solutions

1. Update the SpacetimeDB CLI and module dependencies (spacetimedb-sdk/lib) to matching versions.
2. Review the module for duplicate table/index/reducer names or invalid identifiers and constraints.
3. Try publishing the module instead — publish errors may pinpoint the invalid definition.
4. Simplify the offending definition to isolate which declaration fails validation.

Example fix

// before
#[spacetimedb::table(name = users)]
struct Users; // name/struct mismatch after rename
// after
#[spacetimedb::table(name = users)]
struct User;

// offline lint: ensure unique table names and valid identifiers before extraction
let names: Vec<_> = tables.iter().map(|t| &t.name).collect();
assert_unique(&names, "duplicate table names");

let schema = ModuleDef::try_from(raw).map_err(|e| anyhow!("Module defines an invalid schema: {e}"))?;

When it happens

Trigger: The inspector produced a RawModuleDef that fails ModuleDef validation — e.g. duplicate table/column names, invalid identifiers, constraint or index definitions that violate SpacetimeDB rules — typically from a module written with constructs the extractor mis-translates.

Common situations: Modules using newly added language features with an older CLI; duplicated or conflicting table aliases; invalid column types or constraints in the module source.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Failed to generate table due to validation errors
• Invalid HTTP method
• `table_id` must not be `TableId::SENTINEL` in
• table schema should validate for query builder codegen
• Cannot determine module type from file extension

AI-assisted analysis of clockworklabs/SpacetimeDB@eddf9f5014 (2026-09-20). Data as JSON: /api/errors/7bd85f872ac79b0d. Report an issue: GitHub.

Appendix: source

Thrown at crates/cli/src/schema_extract.rs:172

                    ensure!(status.success(), "Local module schema inspection failed");
                    Ok(())
                }) => result.unwrap_or_else(|_| Err(anyhow::anyhow!("Local module schema inspection timed out"))),
            };
            if result.is_err() {
                // Queue termination, then retain ownership through positive reaping.
                let _ = child.start_kill();
                let status = child
                    .wait()
                    .await
                    .context("Cannot reap failed local module inspector")?;
                observation.reaped(status);
            }
            result?;
            // Neither parser nor validation diagnostics may echo schema literals.
            let SerdeWrapper::<RawModuleDef>(raw) = serde_json::from_slice(&output)
                .map_err(|_| anyhow::anyhow!("Local module inspector returned invalid schema data"))?;
            let schema =
                ModuleDef::try_from(raw).map_err(|_| anyhow::anyhow!("Local module schema validation failed"))?;
            Ok(schema)
        }
        .await;
        let _ = send.send(result);
    });
    (&mut recv).await.context("Local module inspection owner failed")?
}

#[cfg(test)]
mod tests;

View on GitHub (pinned to eddf9f5014)