{"record":{"id":"f31b360ebea5cf7f","repo":"tursodatabase/turso","slug":"failed-to-read-manual-page","errorCode":null,"errorMessage":"Failed to read manual page: {}","messagePattern":"Failed to read manual page: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"cli/manual.rs","lineNumber":136,"sourceCode":"\n            if relative_distance < RELATIVE_SIMILARITY_THRESHOLD {\n                Some((candidate, distance))\n            } else {\n                None\n            }\n        })\n        .min_by_key(|&(_, score)| score)\n        .map(|(name, _)| name)\n}\n\npub fn display_manual(page: Option<&str>, writer: &mut dyn Write) -> anyhow::Result<()> {\n    let page_name = page.unwrap_or(\"index\");\n    let file_name = format!(\"{page_name}.md\");\n\n    if let Some(file) = MANUAL_DIR.get_file(&file_name) {\n        let content = file\n            .contents_utf8()\n            .ok_or_else(|| anyhow::anyhow!(\"Failed to read manual page: {}\", page_name))?;\n        let content = strip_frontmatter(content);\n        if IsTerminal::is_terminal(&std::io::stdout()) {\n            render_in_terminal(content)?;\n        } else {\n            writeln!(writer, \"{content}\")?;\n        }\n        Ok(())\n    } else if page.is_none() {\n        // If no page specified, list available pages\n        return list_available_manuals(writer);\n    } else {\n        let available_pages = MANUAL_DIR\n            .files()\n            .filter_map(|file| file.path().file_stem().and_then(|stem| stem.to_str()));\n        let mut error_message = format!(\"Manual page not found: {page_name}\");\n        if let Some(suggestion) = find_closest_manual_page(page_name, available_pages) {\n            error_message.push_str(&format!(\"\\n\\nDid you mean '.manual {suggestion}'?\"));\n        }","sourceCodeStart":118,"sourceCodeEnd":154,"githubUrl":"https://github.com/tursodatabase/turso/blob/244cde92a7df7f9b8b8b7a4075c35a12977e303e/cli/manual.rs#L118-L154","documentation":"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.","triggerScenarios":"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.","commonSituations":"Contributors editing manual pages on Windows editors that default to UTF-16; merge artifacts corrupting content; CI checkout with text attributes rewriting files.","solutions":["Find the offending file: for f in manual/*.md; do iconv -f UTF-8 -t UTF-8 \"$f\" >/dev/null || echo \"$f\"; done","Convert that file to UTF-8 and rebuild the CLI","Add a CI check that every manual asset decodes as UTF-8"],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"let text = std::str::from_utf8(file.contents())\n    .map_err(|_| anyhow!(\"manual asset {page_name} is not UTF-8\"))?;","typeGuard":"fn is_utf8(bytes: &[u8]) -> bool {\n    std::str::from_utf8(bytes).is_ok()\n}","tryCatchPattern":null,"preventionTips":["CI-check that every embedded manual asset decodes as UTF-8","Configure editors to write UTF-8","Degrade to listing pages instead of failing when one asset is unreadable"],"tags":["cli","manual","utf-8","embedded-assets","rust"],"backgroundTag":"invalid-file-encoding","analyzedSha":"244cde92a7df7f9b8b8b7a4075c35a12977e303e","analyzedAt":"2026-08-20T07:02:18.389Z","contentChangedAt":"2026-08-20T07:02:18.389Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}