tursodatabase/turso · error

first-query runs require one query per connection; use warm

Error message

first-query runs require one query per connection; use warm for repeated transactions

What it means

When state is QueryState::First (first-query measurement), validate() demands exactly one batch with one query per connection, because first-query timing/memory is only meaningful for a single initial query. Any other shape is rejected with guidance to use the warm state for repeated-transaction runs.

Source

Thrown at perf/memory/src/fts.rs:286

impl FtsConfig {
    pub fn validate(&self) -> Result<()> {
        ensure!(self.documents > 0, "documents must be positive");
        ensure!(
            self.corpus
                .cache_pages
                .is_none_or(|pages| (200..=i32::MAX as usize).contains(&pages)),
            "cache pages must be between 200 and i32::MAX"
        );
        ensure!(self.connections > 0, "connections must be positive");
        ensure!(
            self.execution.batches() > 0,
            "queries or transactions must be positive"
        );
        ensure!(
            self.execution.queries_per_batch() > 0,
            "queries per transaction must be positive"
        );
        ensure!(
            !matches!(self.state, QueryState::First)
                || (self.execution.batches() == 1 && self.execution.queries_per_batch() == 1),
            "first-query runs require one query per connection; use warm for repeated transactions"
        );
        self.execution
            .batches()
            .checked_mul(self.execution.queries_per_batch())
            .and_then(|n| n.checked_mul(self.connections))
            .ok_or_else(|| anyhow::anyhow!("total query count overflows usize"))?;
        Ok(())
    }
}

impl Execution {
    pub fn batches(self) -> usize {
        match self {
            Self::Queries(queries) => queries,
            Self::Transactions { per_connection, .. } => per_connection,

View on GitHub (pinned to 492c4a71cd)

Solutions

1. Use one batch with exactly one query per connection when state is First
2. Switch state to QueryState::Warm if you want repeated queries/transactions
3. Split the run: do first-query measurement separately from the warm repeated-transaction measurement

Example fix

// before
FtsConfig { state: QueryState::First, execution: Execution { queries_per_transaction: 5, .. } }
// after
FtsConfig { state: QueryState::Warm, execution: Execution { queries_per_transaction: 5, .. } }

if state == QueryState::First && !(execution.batches() == 1 && execution.queries_per_batch() == 1) {
    return Err(anyhow!("First state requires exactly one query per connection"));
}

if let Err(e) = config.validate() {
    if e.to_string().contains("first-query runs require one query") {
        // switch state to Warm or reduce workload to a single query
    }
}

When it happens

Trigger: Running with state = First while execution.batches() != 1 or queries_per_batch() != 1, e.g. --state first --queries-per-transaction 5 or multiple batches.

Common situations: Combining first-query mode with a workload tuned for warm runs; reusing a warm-run config and only flipping the state flag; scripting that appends extra queries while keeping First state.

Related errors

• index contains {} segment bytes, below requested minimum {};
• documents must be positive
• connections must be positive
• queries or transactions must be positive
• queries per transaction must be positive

AI-assisted analysis of tursodatabase/turso@492c4a71cd (2026-09-13). Data as JSON: /api/errors/8ed007b9dac451f2. Report an issue: GitHub.