{"record":{"id":"b61bdeefb4360a3a","repo":"sinelaw/fresh","slug":"invalid-path-encoding","errorCode":null,"errorMessage":"Invalid path encoding","messagePattern":"Invalid path encoding","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/fresh-plugin-runtime/src/thread.rs","lineNumber":1530,"sourceCode":"/// must run on the plugin thread.\nfn execute_prepared_plugin(\n    runtime: &Rc<RefCell<QuickJsBackend>>,\n    plugins: &mut HashMap<String, TsPluginInfo>,\n    prepared: &PreparedPlugin,\n) -> Result<()> {\n    // Register i18n strings\n    if let Some(ref i18n) = prepared.i18n {\n        runtime\n            .borrow_mut()\n            .services\n            .register_plugin_strings(&prepared.name, i18n.clone());\n        tracing::debug!(\"Loaded i18n strings for plugin '{}'\", prepared.name);\n    }\n\n    let path_str = prepared\n        .path\n        .to_str()\n        .ok_or_else(|| anyhow!(\"Invalid path encoding\"))?;\n\n    let exec_start = std::time::Instant::now();\n    runtime\n        .borrow_mut()\n        .execute_js(&prepared.js_code, path_str)?;\n    let exec_elapsed = exec_start.elapsed();\n\n    tracing::debug!(\n        \"execute_prepared_plugin: plugin '{}' executed in {:?}\",\n        prepared.name,\n        exec_elapsed\n    );\n\n    plugins.insert(\n        prepared.name.clone(),\n        TsPluginInfo {\n            name: prepared.name.clone(),\n            path: prepared.path.clone(),","sourceCodeStart":1512,"sourceCodeEnd":1548,"githubUrl":"https://github.com/sinelaw/fresh/blob/67894ca5463dbd7a89bb31add4627c27d6b79d83/crates/fresh-plugin-runtime/src/thread.rs#L1512-L1548","documentation":"This error is raised when a prepared TypeScript plugin's file path cannot be converted from an OsStr to a valid UTF-8 Rust string via `Path::to_str()`. The runtime needs the path as a `&str` to pass into `execute_js` (typically for `import()` resolution / stack traces inside QuickJS), and non-UTF-8 paths would be silently mangled, so the code fails fast instead. It is a fail-fast guard against OS paths containing invalid Unicode.","triggerScenarios":"Calling the plugin-loading flow (which prepares a plugin and calls `execute_js(&prepared.js_code, path_str)`) with a plugin file whose absolute path contains bytes that are not valid UTF-8. This happens right after 'Loaded i18n strings for plugin ...' during plugin load.","commonSituations":"Plugin directories or filenames created with non-UTF-8 encodings (e.g. Latin-1 filenames from old Samba/NFS mounts, filenames with raw 0x80-0xFF bytes on Linux); plugins installed in directories whose names contain such bytes; moving plugin caches across systems with different filename encodings.","solutions":["Rename the plugin file and its parent directories to use only valid UTF-8 (ASCII) characters.","Check the path with `locale`/`ls` on the host to find the offending filename bytes and fix the mount or filesystem encoding.","If programmatic control is needed, sanitize paths before handing them to the plugin loader, or re-encode with `String::from_utf8_lossy` only if the resulting path is still resolvable.","On Windows, ensure the path does not contain characters outside UTF-16-to-UTF-8 representable ranges; move plugins to a simple ASCII path."],"exampleFix":"// before\nplugins-dir/caf�-plugins/my-plugin.ts   (raw non-UTF-8 byte in dir name)\n\n// after\nplugins-dir/cafe-plugins/my-plugin.ts","handlingStrategy":"validation","validationCode":"fn is_utf8_path(p: &std::path::Path) -> bool {\n    p.to_str().is_some()\n}\n// call before loading:\nif !is_utf8_path(&prepared.path) {\n    eprintln!(\"skip plugin: path is not valid UTF-8: {:?}\", prepared.path);\n}","typeGuard":"fn valid_utf8_path(p: &std::path::Path) -> Option<&str> {\n    p.to_str()\n}","tryCatchPattern":"match load_result {\n    Err(e) if e.to_string().contains(\"Invalid path encoding\") => {\n        eprintln!(\"Plugin skipped: file path is not valid UTF-8; rename the file/directory.\");\n    }\n    Err(e) => return Err(e),\n    Ok(v) => v,\n}","preventionTips":["Keep plugin directories and filenames ASCII/UTF-8 only.","Sanitize paths from user config before passing them to the loader.","When copying plugins from archives or network shares, verify filenames decode as UTF-8.","Log `path.as_os_str()` when a load fails to spot non-UTF-8 bytes early."],"tags":["encoding","filesystem","utf-8","plugin-loading"],"backgroundTag":"invalid-argument-format","analyzedSha":"67894ca5463dbd7a89bb31add4627c27d6b79d83","analyzedAt":"2026-09-13T15:04:03.701Z","contentChangedAt":"2026-09-13T15:04:03.701Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}