Migration can leave generated index accessors pointing at missing index names

[kdletters]

I have a accessor named x3d, and the accessor name in binding will be x_3_d, if i use this accessor, it will panic.

[bfops]

Hi @kdletters, could you add a little more detail? Do you happen to have an example module and an example of the command that panics?

[kdletters]

It seems like a migration problem from 2.2.0 to 2.3.0, schema in database is "x3d" since 2.2.0, but the code generated by 2.3.0 is "x_3_d" for wasm.

[kdletters]

The module instance encountered a fatal error: error while executing at wasm backtrace: 0: 0xac70ae - spacetime_module.wasm!__rustc[b7974e8690430dd9]::rust_panic 1: 0xac707f - spacetime_module.wasm!std[a543996e6e7dbf1e]::panicking::panic_with_hook 2: 0xac6e6f - spacetime_module.wasm!std[a543996e6e7dbf1e]::panicking::panic_handler::{closure#0} 3: 0xac6dd3 - spacetime_module.wasm!std[a543996e6e7dbf1e]::sys::backtrace::__rust_end_short_backtrace::<std[a543996e6e7dbf1e]::panicking::panic_handler::{closure#0}, !> 4: 0xac8e8a - spacetime_module.wasm!__rustc[b7974e8690430dd9]::rust_begin_unwind 5: 0x137fb - spacetime_module.wasm!core[c5930c85a12de822]::panicking::panic_fmt 6: 0x13c1c - spacetime_module.wasm!core[c5930c85a12de822]::result::unwrap_failed 7: 0x82c26a - spacetime_module.wasm!std::sync::once_lock::OnceLock::initialize::hf6c70f364e2f05d4 8: 0x51406d - spacetime_module.wasm!spacetimedb::table::filter::h4a6be52734d2520f 9: 0x510d56 - spacetime_module.wasm!spacetimedb::ProcedureContext::try_with_tx::{{closure}}::h76bfacb7038ec525 10: 0x67e6a2 - spacetime_module.wasm!spacetime_module::runtime::admin_work_visibility::admin_list_work_visibility::invoke::he07c501547760170 11: 0xac08cd - spacetime_module.wasm!call_procedure

[clockwork-labs-bot]

Summary

This looks like a SpacetimeDB schema migration bug. It is not an infrastructure issue.

The short version: an existing database can retain an old index lookup name, while a republished module generated by a newer SDK/runtime asks for a different index lookup name. The first time module code uses that indexed accessor, the generated Wasm cannot resolve the index id and panics.

Failure path

The failing path appears to be:

1. Generated Rust/Wasm index accessors eventually call spacetimedb::sys::index_id_from_name(...).unwrap() the first time an indexed path needs the index id.
2. The host-side lookup can resolve an index by either its canonical name or by an alias stored in st_index_accessor.
3. An existing database was created with one stored index name or alias, for example using an x3d spelling.
4. After republishing with a newer module/schema definition, generated code asks for a different spelling, for example x_3_d, due to the canonical/accessor/case-conversion split.
5. If migration does not preserve that new generated lookup spelling as either the canonical st_index.index_name or an st_index_accessor alias, index_id_from_name returns no such index.
6. The generated .unwrap() then traps. That matches the reported backtrace under spacetimedb::table::filter.

User impact and trigger

This does not look like all pre-existing databases are broken. The trigger is narrower.

A user is likely affected only if all of these are true:

• They have an existing database created/published with an older schema naming result.
• They republish or migrate that database with a newer module/schema definition where an index lookup name changes.
• The change is most likely around identifiers whose case-converted form changes, especially digit or case boundaries such as x3d -> x_3_d.
• The table/index is otherwise compatible enough that publish/migration succeeds or appears to succeed.
• Module code later exercises the affected indexed accessor, for example .filter(...), .find(...), .delete(...), or update through a unique/primary index.

A user would usually encounter this as a runtime module trap after republishing, not necessarily as a publish-time error. Non-indexed paths, such as full table iteration, should not hit this specific failure. Fresh databases created entirely with one consistent version should also be internally consistent. Existing databases whose generated index lookup names do not change should be unaffected.

Regression shape

I would classify this as a migration regression rather than a broad runtime regression. The regression is that republishing across a naming-policy boundary can leave stored index metadata and newly generated module lookup names out of sync. The runtime then exposes the mismatch when the affected index is first used.

Fix notes

The likely fix is in auto-migration/schema metadata handling. For otherwise-identical indexes whose generated lookup/source/accessor spelling changed, migration should preserve or update the relevant alias so both old and new generated lookup names resolve to the same index id. In practice, that likely means updating st_index_accessor or preserving the old/new lookup spelling as an alias instead of allowing the new Wasm module to ask for an index name the database cannot resolve.

There is adjacent work on shub/fix-accessor-migration. From inspection, that branch adds migration steps for table/column accessor aliases and index source-name aliases, but it does not appear to fully cover this baked index accessor lookup mismatch yet.

PR #4725, which adds custom index name = ... support, may be a workaround for some affected users because they can pin/preserve a canonical index name. It is not the general migration fix for existing databases that have already drifted.

[gefjon]

Is the generated code you're describing in the module, and emitted by a macro; or is it on a client, and emitted by spacetime generate/spacetime dev?

[clockwork-labs-bot]

Yes, this is in the module, specifically in the module’s generated table/index accessor code emitted by the #[spacetimedb::table] macro. It is not external client SDK code emitted by spacetime generate or spacetime dev.

The module Wasm includes generated accessor code for indexed table accessors. That code bakes in the index lookup name and calls spacetimedb::sys::index_id_from_name("<index lookup name>").unwrap() at runtime.

So the mismatch is:

• the module’s generated accessor code asks for the new name, e.g. x_3_d
• the migrated database metadata only knows the old name or alias, e.g. x3d
• the first reducer path that uses that module accessor panics