tursodatabase/turso · error · anyhow::Error

Page number must be a positive integer.

Error message

Page number must be a positive integer.

What it means

Thrown by the tursodb CLI dot-command .dbtotxt when the optional page-number argument is zero or negative. dump_database_as_text takes Option<i64> and validates it before rendering anything, because pages in the SQLite file format are 1-indexed (page 1 is the file header). This is pure argument validation at cli/app.rs:2186; no I/O has happened yet.

Source

Thrown at cli/app.rs:2202

                };
                write!(self, "{ch}")?;
            }
            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 {

View on GitHub (pinned to 492c4a71cd)

Solutions

1. Pass a 1-based page number: page 1 is the header, valid range is 1..=page_count
2. Run .dbtotxt with no page argument to dump the whole database instead of one page
3. If the page is computed dynamically, clamp it before use: pgno.max(1) and check it against PRAGMA page_count

Example fix

-- before
.dbtotxt 0
-- ERROR: Page number must be a positive integer.

-- after
.dbtotxt 1

let page_count: i64 = fetch_single_i64(&mut conn.query("PRAGMA page_count")?.unwrap())?;
if let Some(pgno) = page_no {
    anyhow::ensure!(pgno >= 1, "page number must be >= 1");
}

match app.dump_database_as_text(Some(pgno)) {
    Ok(()) => {}
    Err(e) if e.to_string().contains("positive integer") => eprintln!("page must be >= 1, got {pgno}"),
    Err(e) => return Err(e),
}

When it happens

Trigger: Running .dbtotxt with a non-positive page argument, e.g. `.dbtotxt 0` or `.dbtotxt -3`. Programmatically calling dump_database_as_text(Some(pgno)) with a computed pgno that is <= 0.

Common situations: Scripts that loop page numbers starting at 0 instead of 1; a computed offset like page_count - n going negative on an empty or single-page database; copy-pasting examples that treat pages as 0-indexed.

Related errors

• Page number {pgno} is out of bounds. The database only has {
• 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/32532aadce80850f. Report an issue: GitHub.