clockworklabs/SpacetimeDB · error

unexpected error from `datastore_index_scan_point_bsatn`: {e

Error message

unexpected error from `datastore_index_scan_point_bsatn`: {e}

What it means

Internal wrapper used by find/filter helpers on unique columns; it panics when the datastore_index_scan_point_bsatn syscall returns an error. Errors mean the BSATN-encoded point failed to decode as the index's key type or the index id is invalid - i.e. compiled-in metadata disagrees with the deployed database schema.

Source

Thrown at crates/bindings/src/table.rs:455

    let point = IterBuf::serialize(col_val).unwrap();

    let iter = datastore_index_scan_point_bsatn(index_id, &point);
    let mut iter = TableIter::new_with_buf(iter, point);

    // We will always find either 0 or 1 rows here due to the unique constraint.
    let row = iter.next();
    assert!(
        iter.is_exhausted(),
        "`datastore_index_scan_point_bsatn` on unique field cannot return >1 rows"
    );
    row
}

/// See `sys::datastore_index_scan_point_bsatn`.
/// Panics when the aforementioned errors.
fn datastore_index_scan_point_bsatn(index_id: IndexId, point: &[u8]) -> sys::RowIter {
    sys::datastore_index_scan_point_bsatn(index_id, point)
        .unwrap_or_else(|e| panic!("unexpected error from `datastore_index_scan_point_bsatn`: {e}"))
}

/// A read-only handle to a unique (single-column) index.
///
/// This is the read-only version of [`UniqueColumn`].
/// It mirrors [`UniqueColumn`] but only exposes read APIs.
/// It cannot insert or delete rows.
/// It is used by `{table}__ViewHandle` to keep view code read-only at compile time.
///
/// Note, the `Tbl` generic is the read-write table handle `{table}__TableHandle`.
/// This is because read-only indexes still need [`Table`] metadata.
/// The view handle itself deliberately does not implement `Table`.
pub struct UniqueColumnReadOnly<Tbl, ColType, Col> {
    _marker: PhantomData<(Tbl, ColType, Col)>,
}

impl<Tbl: Table, Col: Index + Column<Table = Tbl>> UniqueColumnReadOnly<Tbl, Col::ColType, Col> {
    #[doc(hidden)]

View on GitHub (pinned to 6dee26c6ef)

Solutions

1. Regenerate bindings and rebuild/redeploy so index ids and key types match the deployed schema.
2. Confirm the queried column is declared #[unique] or indexed as expected in the current module source.
3. Align spacetimedb crate and host versions; report an issue with the errno if it persists.

When it happens

Trigger: Searching a unique column (ctx.db.table().col().find(v)) after the module's column type or index definition changed without a matching rebuild; crate/host version mismatch producing incompatible index ids.

Common situations: Schema migration (column type widened/renamed) with stale generated code; deploying to a server of a different version than the toolchain used to build the module.

Related errors

• Failed to get table with name: {table_name}
• unexpected error from `datastore_delete_by_index_scan_point_
• Failed to BSATN-deserialize `{}`: {err:#?}
• {e}
• unique: unexpected error from datastore_delete_by_index_scan

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