tursodatabase/turso · error

documents must be positive

Error message

documents must be positive

What it means

FtsConfig::validate() rejects configurations where documents is zero. The benchmark needs at least one document to build an FTS index and produce meaningful memory numbers, so a non-positive document count fails validation before any benchmark work starts.

Source

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

            while let Some(worker) = workers.join_next().await {
                let batch = worker??;
                result.queries += batch.queries;
                result.rows += batch.rows;
                result.id_sum += batch.id_sum;
            }
            Ok(result)
        }
        .await;
        if result.is_err() {
            workers.shutdown().await;
        }
        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),

View on GitHub (pinned to 492c4a71cd)

Solutions

1. Pass a positive document count, e.g. --documents 10000
2. If documents is computed, check the input value before building FtsConfig
3. Fall back to a sane default when the argument is missing or zero

Example fix

// before
tursodb-memory-fts --documents 0
// after
tursodb-memory-fts --documents 10000

if documents == 0 { return Err(anyhow!("documents must be > 0")); }
let config = FtsConfig { documents, .. };
config.validate()?;

match config.validate() {
    Err(e) if e.to_string().contains("documents must be positive") => {
        // fall back to a default document count
    }
    r => r?,
}

When it happens

Trigger: Constructing FtsConfig or passing CLI args such that documents == 0 (e.g. --documents 0 or a computed default of 0).

Common situations: Typo on the command line; shell variable expansion yielding empty/0; programmatic config where documents comes from an unset or zero-valued parameter.

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

• index contains {} segment bytes, below requested minimum {};
• connections must be positive
• queries or transactions must be positive
• queries per transaction 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/77850a1fe768f5b5. Report an issue: GitHub.