libnyanpasu/clash-nyanpasu · warning

invalid filter: missing `when`

Error message

invalid filter: missing `when`

What it means

Validation guard in apply_filter for object-form filter rules: a filter expressed as ConfigValue::Object must contain a `when` key holding a string, and when it is absent the filter is rejected. Note this is a soft guard — it logs a StepLogEntry::warn and returns the items unchanged instead of propagating an error, so an invalid filter rule is skipped rather than failing the whole overlay step.

Source

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

        ConfigValue::Object(actions) => {
            let Some(ConfigValue::String(when)) = actions.get("when") else {
                logs.push(StepLogEntry::warn("invalid filter: missing `when`"));
                return items;
            };

View on GitHub (pinned to f7dbce2997)

Solutions

1. Add a `when` predicate expression to the filter object
2. Check filter syntax: object filters must contain `when` plus an action key
3. Use a non-object (scalar/array) filter form if no predicate is needed
4. Enable step logging to confirm which filter block is malformed

Example fix

// before
filter:
  merge: { extra: true }
// after
filter:
  when: "item.name != 'DIRECT'"
  merge: { extra: true }

if let ConfigValue::Object(actions) = &filter {
    assert!(matches!(actions.get("when"), Some(ConfigValue::String(_))), "filter object requires a `when` string predicate");
}

fn is_valid_object_filter(f: &ConfigValue) -> bool {
    matches!(f, ConfigValue::Object(a) if matches!(a.get("when"), Some(ConfigValue::String(_))))
}

When it happens

Trigger: A filter step's filter value is a mapping of actions (merge/remove/override) but has no `when` predicate string.

Common situations: Hand-written filter configs omitting `when`; ported legacy merge configs whose action object predates the `when` requirement.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• invalid filter: no action
• invalid filter value, skipped
• Invalid theme color: {}
• Invalid theme color: {}
• profiles.yaml failed validation: {errors:?}

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