What causes "Failed to track query: {}" in dmtrKovalenko/fff?

Inspect the inner error payload to identify the database failure cause.

Failed to track query

Error message

Failed to track query: {}

What it means

fff_track_query calls QueryTracker::track_query_completion and wraps any internal database error (e.g. LMDB write failure) in this message. The call returns an error result with value 0 instead of the success value 1.

Solutions

Inspect the inner error payload to identify the database failure cause.
Check disk space and write permissions on the directory holding the query history DB.
Treat tracking as best-effort: log and continue, since losing one tracked query is harmless.
If the DB is corrupt or full, remove/rebuild the query history database files.
Retry the call once in case of a transient lock contention.

Example fix

null

Defensive patterns

Strategy: fallback

Try / catch

local res = fff.track_query(inst, q, path)
if res.is_err then log('query tracking failed (non-critical): ' .. res.message) end

Prevention

Monitor disk space where the query history DB lives.
Keep the DB directory writable and on a non-read-only mount.
Design the host to tolerate lost tracking events.

When it happens

Trigger: Calling fff_track_query when the query tracker's underlying database cannot be written: disk full, LMDB map size exhausted, database file locked or corrupted, or I/O permission errors.

Common situations: Disk quota/full disk on the machine hosting the frecency DB; concurrent access corrupting or blocking the LMDB environment; read-only mount for the DB directory; very large query history hitting environment limits.

Related errors

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

Appendix: source

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

        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),
    };

    if let Some(ref mut tracker) = *qt_guard
        && let Err(e) = tracker.track_query_completion(query_str, &project_path, &file_path)
    {
        return FffResult::err(&format!("Failed to track query: {}", e));
    }

    FffResult::ok_int(1)
}

/// Get historical query by offset (0 = most recent).
///
/// ## Safety
/// `fff_handle` must be a valid instance pointer from `fff_create_instance`.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn fff_get_historical_query(
    fff_handle: *mut c_void,
    offset: u64,
) -> *mut FffResult {
    let inst = match unsafe { instance_ref(fff_handle) } {
        Ok(i) => i,
        Err(e) => return e,
    };

View on GitHub (pinned to 7f8537e70f)