libnyanpasu/clash-nyanpasu · warning · StepLogEntry

filter `when` failed, treated as false: {error}

Error message

filter `when` failed, treated as false: {error}

What it means

During overlay filter application, the `when` predicate (a script expression) failed to evaluate for an item. The library treats the predicate as false, meaning the item is filtered out, and logs a warning instead of aborting the whole overlay step. This keeps a single bad predicate from breaking the entire config pipeline.

Source

Thrown at backend/nyanpasu-config/src/runtime/executor/overlay.rs:210

                FilterAction::Override(replacement)
            } else if let Some(merge) = actions
                .get("merge")
                .filter(|value| value.as_object_arc().is_some())
            {
                FilterAction::Merge(merge)
            } else if let Some(ConfigValue::Array(paths)) = actions.get("remove") {
                FilterAction::Remove(paths)
            } else {
                logs.push(StepLogEntry::warn("invalid filter: no action"));
                return items;
            };
            items
                .into_iter()
                .map(|item| {
                    let hit = match runner.eval_item_predicate(when, &item) {
                        Ok(hit) => hit,
                        Err(error) => {
                            logs.push(StepLogEntry::warn(format!(
                                "filter `when` failed, treated as false: {error}"
                            )));
                            false
                        }
                    };
                    if !hit {
                        return item;
                    }
                    match &action {
                        FilterAction::Expr(expr) => match runner.eval_item_expr(expr, &item) {
                            Ok(next) => next,
                            Err(error) => {
                                logs.push(StepLogEntry::warn(format!(
                                    "filter `expr` failed, item kept: {error}"
                                )));
                                item
                            }
                        },

View on GitHub (pinned to f7dbce2997)

Solutions

  1. Fix the `when` expression syntax/fields referenced by the filter rule in the overlay document
  2. Check the StepLogEntry warning text for the underlying script error ({error} interpolates the actual cause)
  3. Verify the predicate only references fields that exist on every item being filtered
  4. Test the expression with eval_item_predicate directly on a sample item

Example fix

// before: references possibly-missing field
{"when": "item.port > 1000"}
// after: guard against missing field
{"when": "'port' in item and item.port > 1000"}
Defensive patterns

Strategy: validation

Validate before calling

fn valid_when(when: &str, sample: &ConfigValue) -> bool { ScriptRunner::default().eval_item_predicate(when, sample).is_ok() }

Try / catch

match runner.eval_item_predicate(when, &item) { Ok(hit) => hit, Err(e) => { log::warn!("when failed: {e}"); false } }

Prevention

When it happens

Trigger: apply_filter calls runner.eval_item_predicate(when, &item) and the script runner returns Err — e.g. the `when` expression references an undefined field, has a syntax error, uses an unsupported operator, or throws at runtime for a particular item.

Common situations: A user-authored overlay filter rule with a typo in the `when` expression; a `when` predicate written against a different schema version where the referenced item field no longer exists; script expressions evaluated against items whose shape varies (missing keys).

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of libnyanpasu/clash-nyanpasu@f7dbce2997 (2026-09-08). Data as JSON: /api/errors/1ada7adf7c617986. Report an issue: GitHub.