{"record":{"id":"8d499fa655431ffc","repo":"PRQL/prql","slug":"path-is-not-valid-utf-8","errorCode":null,"errorMessage":"Path `{}` is not valid UTF-8","messagePattern":"Path `(.+?)` is not valid UTF-8","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"prqlc/prqlc/src/cli/mod.rs","lineNumber":323,"sourceCode":"                let sources = read_files(input)?;\n                let root = sources.root;\n\n                for (path, source) in sources.sources {\n                    let ast = prql_to_pl(&source)?;\n\n                    // If we're writing to stdout (though could this be nicer?\n                    // We're discarding many of the benefits of Clio here...)\n                    if path.as_os_str() == \"\" {\n                        let mut output: Output = Output::new(input.path())?;\n                        output.write_all(&pl_to_prql(&ast)?.into_bytes())?;\n                        break;\n                    }\n\n                    let path_buf = root\n                        .as_ref()\n                        .map_or_else(|| path.clone(), |root| root.join(&path));\n                    let path_str = path_buf.to_str().ok_or_else(|| {\n                        anyhow!(\"Path `{}` is not valid UTF-8\", path_buf.display())\n                    })?;\n                    let mut output: Output = Output::new(path_str)?;\n\n                    output.write_all(&pl_to_prql(&ast)?.into_bytes())?;\n                }\n                Ok(())\n            }\n            Command::ShellCompletion { shell } => {\n                shell.generate(&mut Cli::command(), &mut std::io::stdout());\n                Ok(())\n            }\n            Command::Debug(DebugCommand::Ast) => {\n                prqlc::ir::pl::print_mem_sizes();\n                Ok(())\n            }\n            Command::Debug(DebugCommand::JsonSchema { ir_type }) => {\n                let schema = match ir_type {\n                    IntermediateRepr::Pl => schema_for!(pl::ModuleDef),","sourceCodeStart":305,"sourceCodeEnd":341,"githubUrl":"https://github.com/PRQL/prql/blob/e164e249b99485890036eb60f57c37520379b240/prqlc/prqlc/src/cli/mod.rs#L305-L341","documentation":"When writing compiler output (e.g. pl_to_prql output for a format/translate step) to an output path, the CLI needs a &str path. If the constructed path is not valid UTF-8, run() returns this anyhow error with the path's display form. Non-UTF-8 paths are rejected rather than lossily converted.","triggerScenarios":"Running a prqlc command whose output is redirected to a file whose full path contains non-UTF-8 bytes (e.g. invalid UTF-8 in a filename or a parent directory name), possibly combined with --root.","commonSituations":"Files created by scripts with bytes outside valid UTF-8 (common with Latin-1 encoded names), mounts with opaque byte names, or locales producing non-UTF-8 filenames on Unix.","solutions":["Rename the file/directory so the full path is valid UTF-8","Write to stdout (omit the output path argument) and redirect in the shell instead","If --root is used, verify the joined root + relative path is UTF-8","Check the path with `iconv` / `printf %s \"$p\" | iconv -f utf-8 -t utf-8` to locate offending bytes"],"exampleFix":"# before (path contains invalid bytes)\nprqlc compile q.prql > \"$OUT_DIR/café-latin1-name.sql\"\n# after (valid UTF-8 path)\nprqlc compile q.prql > \"$OUT_DIR/cafe-name.sql\"","handlingStrategy":"validation","validationCode":"# Verify output path is valid UTF-8 before running\npython3 -c \"import sys; open(sys.argv[1]).close()\" \"$OUT_FILE\" 2>/dev/null || echo 'path not usable/UTF-8'","typeGuard":null,"tryCatchPattern":"if ! out=$(prqlc compile q.prql 2>&1); then echo \"$out\" | grep -q 'not valid UTF-8' && echo 'rename output path'; fi","preventionTips":["Keep project paths ASCII/UTF-8 clean","Redirect to stdout instead of passing output paths","Sanitize filenames generated by scripts (strip non-UTF-8 bytes)"],"tags":["cli","filesystem","utf-8"],"backgroundTag":"invalid-argument-format","analyzedSha":"e164e249b99485890036eb60f57c37520379b240","analyzedAt":"2026-09-09T12:18:38.727Z","contentChangedAt":"2026-09-09T12:18:38.727Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}