dmtrKovalenko/fff · error

opts is null

Error message

opts is null

What it means

fff_create_instance_with requires a pointer to an FffCreateOptions struct. A null pointer carries no configuration, so the call fails fast instead of dereferencing null. Use fff_create_instance if you want defaults with no options struct.

Solutions

1. Pass a valid FffCreateOptions pointer with version set to FFF_CREATE_OPTIONS_VERSION.
2. Use fff_create_instance(base_path) instead if no options struct is needed.
3. In bindings, construct the options object/struct explicitly before calling.
4. Check for null in the binding layer and raise a clear error early.

Example fix

// before
fff_create_instance_with(null);
// after
FffCreateOptions opts = { .version = FFF_CREATE_OPTIONS_VERSION, .base_path = "/repo" };
fff_create_instance_with(&opts);

if (!opts) throw new Error('fff: options object required by fff_create_instance_with');

function isValidCreateOptions(o) { return o !== null && o !== undefined && o.version >= 1 && typeof o.base_path === 'string' && o.base_path.length > 0; }

if (!opts) return useDefaultInstance(); // or throw
const res = fff_create_instance_with(buildOptsStruct(opts));
if (!res.ok) throw new Error(res.error);

When it happens

Trigger: Calling fff_create_instance_with(NULL); a binding that passes a zero-initialized options pointer variable; forgetting to allocate the struct in C or pass the options object in a higher-level binding.

Common situations: Hand-written FFI bindings that drop the options argument; code paths that conditionally build options and pass undefined/null; migrating from fff_create_instance and using the wrong entry point.

Related errors

• Instance handle is null. Create one with…
• Unsupported FffCreateOptions version
• opts.base_path is null or empty
• Failed to init tracing
• Failed to acquire frecency lock

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

Appendix: source

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

/// Create a new file finder instance from a versioned [`FffCreateOptions`] struct.
///
/// Populate the struct, set `version` to [`FFF_CREATE_OPTIONS_VERSION`], pass by
/// pointer. New fields are only appended; older `version` values keep working.
/// FFI bindings needing struct-by-value should use [`fff_create_instance_with_value`].
///
/// `opts.base_path` is required (non-NULL, non-empty). Zero `cache_budget_*`
/// values are auto-computed from repo size after the initial scan.
///
/// ## Safety
/// * `opts` must be a valid pointer to an `FffCreateOptions` whose `version`
///   is in the range `1..=FFF_CREATE_OPTIONS_VERSION`.
/// * All string pointers inside `opts` must be valid null-terminated UTF-8
///   or NULL.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn fff_create_instance_with(opts: *const FffCreateOptions) -> *mut FffResult {
    if opts.is_null() {
        return FffResult::err("opts is null");
    }
    let opts = unsafe { &*opts };
    if opts.version == 0 || opts.version > FFF_CREATE_OPTIONS_VERSION {
        return FffResult::err(&format!(
            "Unsupported FffCreateOptions version {} (library understands up to {})",
            opts.version, FFF_CREATE_OPTIONS_VERSION
        ));
    }

    let base_path_str = match unsafe { cstr_to_str(opts.base_path) } {
        Some(s) if !s.is_empty() => s.to_string(),
        _ => return FffResult::err("opts.base_path is null or empty"),
    };

    if let Some(log_path) = unsafe { optional_cstr(opts.log_file_path) } {
        let level = unsafe { optional_cstr(opts.log_level) };
        if let Err(e) = fff::log::init_tracing(log_path, level, None) {
            return FffResult::err(&format!("Failed to init tracing: {}", e));

View on GitHub (pinned to 7f8537e70f)