tursodatabase/turso · error · anyhow::Error

Page number {pgno} is out of bounds. The database only has {

Error message

Page number {pgno} is out of bounds. The database only has {} pages.

What it means

Thrown by .dbtotxt when the requested page number exceeds the actual page count of the open database. The count comes from fetch_db_metadata(), which reads the database header, and the check at cli/app.rs:2189 runs before any page is rendered. The message reports both the requested page and the real page count.

Source

Thrown at cli/app.rs:2205

            writeln!(self)?;
        }
        Ok(())
    }

    fn dump_database_as_text(&mut self, page_no: Option<i64>) -> anyhow::Result<()> {
        let metadata = self.fetch_db_metadata()?;
        tracing::debug!(
            page_size = metadata.page_size,
            page_count = metadata.page_count,
            "Fetched metadata"
        );

        if let Some(pgno) = page_no {
            if pgno <= 0 {
                anyhow::bail!("Page number must be a positive integer.");
            }
            if pgno > metadata.page_count {
                anyhow::bail!(
                    "Page number {pgno} is out of bounds. The database only has {} pages.",
                    metadata.page_count
                );
            }
        }

        writeln!(
            self,
            "| size {} pagesize {} filename {}",
            metadata.page_count * metadata.page_size,
            metadata.page_size,
            &metadata.filename
        )?;

        let dump_sql = if let Some(pgno) = page_no {
            format!("SELECT pgno, data FROM sqlite_dbpage WHERE pgno = {pgno}")
        } else {
            "SELECT pgno, data FROM sqlite_dbpage ORDER BY pgno".to_string()

View on GitHub (pinned to 492c4a71cd)

Solutions

1. Re-run with a page number between 1 and the page count shown in the error message
2. Query the true count first: PRAGMA page_count (or read the '| size N pagesize P' header .dbtotxt prints)
3. If another connection may have vacuumed or replaced the file, reopen the database and retry

Example fix

-- before
.dbtotxt 42
-- ERROR: Page number 42 is out of bounds. The database only has 5 pages.

-- after
.dbtotxt 5

let page_count: i64 = fetch_single_i64(&mut stmt)?; // PRAGMA page_count
let pgno = pgno.clamp(1, page_count);

match app.dump_database_as_text(Some(pgno)) {
    Ok(()) => {}
    Err(e) if e.to_string().contains("out of bounds") => eprintln!("page {pgno} beyond page_count; skipping"),
    Err(e) => return Err(e),
}

When it happens

Trigger: `.dbtotxt 42` on a database that has fewer than 42 pages; calling dump_database_as_text(Some(n)) where n > metadata.page_count, e.g. after the file was vacuumed, truncated, or replaced by a smaller one.

Common situations: Hard-coded page numbers taken from a dump of a larger database; another connection vacuumed or replaced the file between your assumption and the run; freshly created or empty databases with very few pages.

Related errors

• Page number must be a positive integer.
• Failed to read manual page: {}
• Manual page not found: {page_name}
• Could not determine home directory
• Error setting Ctrl-C handler

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