What causes "cache pages must be between 200 and i32::MAX" in tursodatabase/turso?

Set cache_pages to a value between 200 and 2147483647

cache pages must be between 200 and i32::MAX

Error message

cache pages must be between 200 and i32::MAX

What it means

FtsConfig::validate() requires cache_pages, when provided, to be within 200..=i32::MAX. Very small page caches make the benchmark meaningless or break assumptions, and the value is stored as an i32 (SQLite cache_size), so values above i32::MAX cannot be represented. None means 'use default' and is allowed.

Source

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

                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),
            "first-query runs require one query per connection; use warm for repeated transactions"

View on GitHub (pinned to 492c4a71cd)

Solutions

Set cache_pages to a value between 200 and 2147483647
Omit cache_pages (leave it None) to use the default cache size
If you intended bytes, convert to page count first (bytes / page_size) and clamp into range

Example fix

// before
CorpusConfig { cache_pages: Some(50), .. }
// after
CorpusConfig { cache_pages: Some(2000), .. }

Defensive patterns

Strategy: validation

Validate before calling

if let Some(pages) = cache_pages {
    if !(200..=i32::MAX as usize).contains(&pages) {
        return Err(anyhow!("cache pages must be within 200..=i32::MAX"));
    }
}

Try / catch

if let Err(e) = config.validate() {
    if e.to_string().contains("cache pages") {
        // clamp or unset cache_pages and rebuild config
    }
}

Prevention

Remember the value is pages, not bytes — convert before passing
Clamp user input: cache_pages.map(|p| p.clamp(200, i32::MAX as usize))
Prefer leaving cache_pages as None unless tuning deliberately

When it happens

Trigger: Setting corpus.cache_pages to Some(n) with n < 200 or n > i32::MAX (e.g. --cache-pages 100 or --cache-pages 99999999999999).

Common situations: Trying to simulate a tiny cache with a sub-200 value; passing a byte-sized or 64-bit cache value that overflows i32; unit confusion (pages vs bytes).

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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