tursodatabase/turso · warning

Failed to read manual page: {}

Error message

Failed to read manual page: {}

What it means

Thrown while rendering .manual: the requested page was found in MANUAL_DIR (the embedded include_dir asset bundle) but its bytes are not valid UTF-8 (cli/manual.rs:136). Because the pages are compiled into the binary, this indicates a corrupted or mis-encoded asset checked into the source tree, not a runtime file problem.

Source

Thrown at cli/manual.rs:136

            if relative_distance < RELATIVE_SIMILARITY_THRESHOLD {
                Some((candidate, distance))
            } else {
                None
            }
        })
        .min_by_key(|&(_, score)| score)
        .map(|(name, _)| name)
}

pub fn display_manual(page: Option<&str>, writer: &mut dyn Write) -> anyhow::Result<()> {
    let page_name = page.unwrap_or("index");
    let file_name = format!("{page_name}.md");

    if let Some(file) = MANUAL_DIR.get_file(&file_name) {
        let content = file
            .contents_utf8()
            .ok_or_else(|| anyhow::anyhow!("Failed to read manual page: {}", page_name))?;
        let content = strip_frontmatter(content);
        if IsTerminal::is_terminal(&std::io::stdout()) {
            render_in_terminal(content)?;
        } else {
            writeln!(writer, "{content}")?;
        }
        Ok(())
    } else if page.is_none() {
        // If no page specified, list available pages
        return list_available_manuals(writer);
    } else {
        let available_pages = MANUAL_DIR
            .files()
            .filter_map(|file| file.path().file_stem().and_then(|stem| stem.to_str()));
        let mut error_message = format!("Manual page not found: {page_name}");
        if let Some(suggestion) = find_closest_manual_page(page_name, available_pages) {
            error_message.push_str(&format!("\n\nDid you mean '.manual {suggestion}'?"));
        }

View on GitHub (pinned to 244cde92a7)

Solutions

1. Find the offending file: for f in manual/*.md; do iconv -f UTF-8 -t UTF-8 "$f" >/dev/null || echo "$f"; done
2. Convert that file to UTF-8 and rebuild the CLI
3. Add a CI check that every manual asset decodes as UTF-8

let text = std::str::from_utf8(file.contents())
    .map_err(|_| anyhow!("manual asset {page_name} is not UTF-8"))?;

fn is_utf8(bytes: &[u8]) -> bool {
    std::str::from_utf8(bytes).is_ok()
}

When it happens

Trigger: A manual .md file saved as UTF-16 or Latin-1 committed to the CLI's manual directory; build tooling or git filters mangling asset bytes; binary garbage merged into a page.

Common situations: Contributors editing manual pages on Windows editors that default to UTF-16; merge artifacts corrupting content; CI checkout with text attributes rewriting files.

Related errors

• Manual page not found: {page_name}
• Error: file "{}" is not valid UTF-8 text – {}
• Could not determine home directory
• Error setting Ctrl-C handler
• InvalidData

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