stalwartlabs/stalwart · error

Failed to scan keys

Error message

Failed to scan keys

What it means

This panic comes from `store.iterate(...).await.expect("Failed to scan keys")` inside `store_console`'s interactive `scan <from_key> <to_key>` command. The store's `iterate` call returned an `Err`, i.e. the underlying storage backend (FoundationDB, PostgreSQL, MySQL, SQLite, RocksDB, etc.) failed while opening a cursor/range scan over the key range, so the console aborts instead of printing entries.

Source

Thrown at crates/common/src/manager/console.rs:88

                                AnyKey {
                                    subspace: to_subspace,
                                    key: to_key.collect::<Vec<_>>(),
                                },
                            )
                            .set_values(
                                ![SUBSPACE_INDEXES, SUBSPACE_REGISTRY_IDX].contains(&from_subspace),
                            ),
                            |key, value| {
                                print!("{}", char::from(from_subspace));
                                print_escaped(key);
                                print!(" : ");
                                print_escaped(value);
                                println!();
                                Ok(true)
                            },
                        )
                        .await
                        .expect("Failed to scan keys");
                }
            }
            "delete" => match (parts.get(1), parts.get(2)) {
                (Some(from_key), Some(to_key)) => {
                    if let (Some(from_key), Some(to_key)) = (parse_key(from_key), parse_key(to_key))
                    {
                        let mut from_key = from_key.into_iter();
                        let mut to_key = to_key.into_iter();

                        let from_key = AnyKey {
                            subspace: from_key.next().unwrap(),
                            key: from_key.collect::<Vec<_>>(),
                        };
                        let to_key = AnyKey {
                            subspace: to_key.next().unwrap(),
                            key: to_key.collect::<Vec<_>>(),
                        };

View on GitHub (pinned to e962003857)

Solutions

1. Check the underlying store is reachable: verify store host/port/credentials in the config and that the DB server is running.
2. Read the error message printed by the panic (it wraps the backend error) to identify the driver-specific failure and fix it accordingly.
3. Test connectivity from the server host (e.g. psql/mysql client, fdb status) before retrying the scan.
4. Retry the scan command after restoring the connection; if it persists, narrow the key range — an extremely large range can hit backend timeouts.

// before scanning, verify store availability
if matches!(store, Store::None) {
    eprintln!("No store available. Verify your configuration.");
    return;
}

match store.iterate(params, callback).await {
    Ok(()) => {}
    Err(err) => eprintln!("Failed to scan keys: {}", err), // handle instead of .expect
}

When it happens

Trigger: Running `scan <from_key> <to_key>` in the Stalwart store console when the backend connection is down or times out, the store is unavailable (network partition, DB restarted), the key range is rejected by the backend, or the driver returns an error mid-iteration.

Common situations: Administrators debugging a store whose database was stopped or unreachable (wrong host/port in config, DB container not running); expired DB credentials; network/firewall issues between the console process and the datastore; backend driver errors surfaced only during range scans.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

• Failed to delete keys
• Migration aborted: {message}
• Failed to decode base64
• unwrap_tls called on non-TLS acceptor
• Unknown database schema version, expected {} or below, found

AI-assisted analysis of stalwartlabs/stalwart@e962003857 (2026-09-06). Data as JSON: /api/errors/b665e60bb180fc94. Report an issue: GitHub.