dmtrKovalenko/fff · warning

Failed to canonicalize path

Error message

Failed to canonicalize path: {}

What it means

fff_track_query canonicalizes the provided file path via fff::path_utils::canonicalize; if canonicalization fails (path does not exist, permission denied, or symlink loop), the error is wrapped and returned. Query history records canonical paths, so unresolvable paths are rejected.

Solutions

1. Check that the file exists (and is readable) before calling fff_track_query.
2. Pass an absolute, real filesystem path — not buffer names or virtual paths.
3. Ignore this error in the host app: tracking is best-effort and non-critical.
4. Refresh the path from the editor's buffer state in case the file moved.

Example fix

// before
fff_track_query(inst, q, c"~/notes.md"); // tilde not expanded, canonicalize fails
// after
let abs = expanduser("~/notes.md");
if std::path::Path::new(&abs).exists() { fff_track_query(inst, q, abs); }

if vim.fn.filereadable(path) == 0 then return end
path = vim.fn.fnamemodify(path, ':p')

local res = fff.track_query(inst, q, path)
if res.is_err then log('track skipped: path not canonicalizable') end -- best-effort

When it happens

Trigger: Calling fff_track_query with a path that does not exist on disk, was deleted between selection and tracking, is unreadable due to permissions, or contains an unresolvable symlink chain.

Common situations: Tracking a query for a file that was closed and deleted in the meantime; passing a relative or virtual path (e.g. a scratch buffer name like '[No Name]') instead of a real file; running in a container where the original path mount is gone.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• Path constraint must be relative to the workspace
• Query is null or invalid UTF-8
• File path is null or invalid UTF-8
• Unsupported FffWatchOptions version
• ignore_count > 0 but ignore is NULL

AI-assisted analysis of dmtrKovalenko/fff@7f8537e70f (2026-09-10). Data as JSON: /api/errors/5262ac87097d017a. Report an issue: GitHub.

Appendix: source

Thrown at crates/fff-c/src/lib.rs:1084

) -> *mut FffResult {
    let inst = match unsafe { instance_ref(fff_handle) } {
        Ok(i) => i,
        Err(e) => return e,
    };

    let query_str = match unsafe { cstr_to_str(query) } {
        Some(s) => s,
        None => return FffResult::err("Query is null or invalid UTF-8"),
    };

    let path_str = match unsafe { cstr_to_str(file_path) } {
        Some(s) => s,
        None => return FffResult::err("File path is null or invalid UTF-8"),
    };

    let file_path = match fff::path_utils::canonicalize(path_str) {
        Ok(p) => p,
        Err(e) => return FffResult::err(&format!("Failed to canonicalize path: {}", e)),
    };

    let project_path = {
        let guard = match inst.picker.read() {
            Ok(g) => g,
            Err(_) => return FffResult::ok_int(0),
        };
        match guard.as_ref() {
            Some(p) => p.base_path().to_path_buf(),
            None => return FffResult::ok_int(0),
        }
    };

    let mut qt_guard = match inst.query_tracker.write() {
        Ok(q) => q,
        Err(_) => return FffResult::ok_int(0),
    };

View on GitHub (pinned to 7f8537e70f)