tursodatabase/turso · error

queries per transaction must be positive

Error message

queries per transaction must be positive

What it means

Validation guard in FtsConfig::validate (called from prepare/main of the memory benchmark's FTS workload): the FTS configuration is checked before the benchmark runs, and the supplied configuration has documents <= 0, connections <= 0, or queries-per-transaction (execution batches) <= 0. This specific message fires when execution.batches() — the number of queries divided by transactions — is zero or negative, i.e. either queries or transactions is zero, so no measurable work would be performed.

Source

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

        result
    }
}

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 {

View on GitHub (pinned to 492c4a71cd)

Solutions

1. Set queries per transaction to a positive value, e.g. --queries-per-transaction 10
2. Default the value to 1 when unset before constructing FtsConfig
3. Check how queries_per_batch() is derived if it is computed from other fields

Example fix

// before
Execution { queries_per_transaction: 0, .. }
// after
Execution { queries_per_transaction: 10, .. }

if queries_per_transaction == 0 { return Err(anyhow!("queries per transaction must be > 0")); }

if let Err(e) = config.validate() {
    if e.to_string().contains("queries per transaction") {
        // default the field to 1 and rebuild
    }
}

When it happens

Trigger: Configuring a transactional run where execution.queries_per_batch() computes to 0 — e.g. queries_per_transaction set to 0 or derived from a zero division/default.

Common situations: --queries-per-transaction 0 on the command line; programmatic Execution built with a zero field; config template with a placeholder never filled in.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• queries or transactions must be positive
• index contains {} segment bytes, below requested minimum {};
• documents must be positive
• connections must be positive
• first-query runs require one query per connection; use warm

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