napi-rs/napi-rs · error · InvalidArg

Invalid key filter [ ]

Error message

Invalid key filter [{}]

What it means

This error is raised converting a raw `sys::KeyFilter` bitmask/enum value into the safe `KeyFilter` Rust enum during object key enumeration. Only the known variants (all_properties, writable, enumerable, configurable, skip_strings, skip_symbols) are accepted; any other value yields `Status::InvalidArg`.

Solutions

1. Use the safe `KeyFilter` Rust enum variants instead of raw sys values
2. Rebuild with napi-sys matching your target Node version
3. Verify no unsafe transmute of arbitrary integers into sys::KeyFilter exists in your code

Example fix

// before
let filter: sys::KeyFilter = unsafe { std::mem::transmute(0xFFu32) };
// after
let filter = KeyFilter::AllProperties;

let filter = KeyFilter::AllProperties; // safe variant only

When it happens

Trigger: Enumerating object properties with key filter options where the raw `napi_key_filter` value does not match any known variant — from corrupted/foreign enum values, version drift between napi-sys and Node headers, or unsafe transmutes of raw integers.

Common situations: Hand-building raw key filters in unsafe FFI code; building against mismatched Node header versions that redefine filter bit values; copy-pasted raw values from a different N-API version.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Invalid key collection mode
• Invalid key conversion
• InvalidArg
• Object is not array
• Invalid argument, nothing attach to js_object

AI-assisted analysis of napi-rs/napi-rs@39bd1205e4 (2026-09-13). Data as JSON: /api/errors/cd20f317783c2c75. Report an issue: GitHub.

Appendix: source

Thrown at crates/napi/src/bindgen_runtime/js_values/object.rs:1054

  Enumerable,
  Configurable,
  SkipStrings,
  SkipSymbols,
}

#[cfg(feature = "napi6")]
impl TryFrom<sys::napi_key_filter> for KeyFilter {
  type Error = Error;

  fn try_from(value: sys::napi_key_filter) -> Result<Self> {
    match value {
      sys::KeyFilter::all_properties => Ok(Self::AllProperties),
      sys::KeyFilter::writable => Ok(Self::Writable),
      sys::KeyFilter::enumerable => Ok(Self::Enumerable),
      sys::KeyFilter::configurable => Ok(Self::Configurable),
      sys::KeyFilter::skip_strings => Ok(Self::SkipStrings),
      sys::KeyFilter::skip_symbols => Ok(Self::SkipSymbols),
      _ => Err(Error::new(
        crate::Status::InvalidArg,
        format!("Invalid key filter [{value}]"),
      )),
    }
  }
}

#[cfg(feature = "napi6")]
impl From<KeyFilter> for sys::napi_key_filter {
  fn from(value: KeyFilter) -> Self {
    match value {
      KeyFilter::AllProperties => sys::KeyFilter::all_properties,
      KeyFilter::Writable => sys::KeyFilter::writable,
      KeyFilter::Enumerable => sys::KeyFilter::enumerable,
      KeyFilter::Configurable => sys::KeyFilter::configurable,
      KeyFilter::SkipStrings => sys::KeyFilter::skip_strings,
      KeyFilter::SkipSymbols => sys::KeyFilter::skip_symbols,
    }

View on GitHub (pinned to 39bd1205e4)