apache/skywalking · error · IllegalArgumentException

filter expression [{}] not found

Error message

filter expression [{}] not found

What it means

Thrown by FilterMatchers.find() when an OAL filter expression references a matcher type that is not in the registry keyed by type name. The registry is built by scanning matcher classes (registered with annotations such as BooleanFilterMatcher); 'find' is called during OAL code generation to resolve the Java matcher class for a filter used in an OAL metric rule. If the type string does not match any registered key (neither the annotated value nor the uncapitalized class-name default), the lookup fails fast.

Source

Thrown at oap-server/oal-rt/src/main/java/org/apache/skywalking/oal/v2/metadata/FilterMatchers.java:84

                    matchersKeyedByType.put(defaultTypeName, new MatcherInfo(clazz, false));
                }
            }

            if (booleanFilterMatcher != null) {
                for (final String type : booleanFilterMatcher.value()) {
                    matchersKeyedByType.put(type, new MatcherInfo(clazz, true));
                }
                if (booleanFilterMatcher.value().length == 0) {
                    final String defaultTypeName = StringUtils.uncapitalize(clazz.getSimpleName());
                    matchersKeyedByType.put(defaultTypeName, new MatcherInfo(clazz, true));
                }
            }
        }
    }

    public MatcherInfo find(final String type) {
        if (!matchersKeyedByType.containsKey(type)) {
            throw new IllegalArgumentException("filter expression [" + type + "] not found");
        }
        return matchersKeyedByType.get(type);
    }

    @Getter
    @AllArgsConstructor
    public static class MatcherInfo {
        private final Class<?> matcher;
        private final boolean isBooleanType;
    }
}

View on GitHub (pinned to 102af09b4a)

Solutions

  1. Check the exact type string in the error (e.g. 'greaterMatch') and grep the codebase for a matcher class whose annotation value or uncapitalized simple name equals it; if none, the operator is unsupported for that value type
  2. If you are adding a new filter capability, create the matcher class and register it with the appropriate matcher annotation (e.g. @BooleanFilterMatcher) in the scanned package, then rebuild so the registry picks it up
  3. Rewrite the OAL filter to use an operator/value-type combination that maps to an existing matcher (see MetricDefinitionEnricher.mapOperatorToExpressionType for the supported mappings)
  4. Verify no typo in the expression-type string if you modified codegen: the key must exactly match the annotation value or StringUtils.uncapitalize(SimpleName)

Example fix

// before (OAL)
from EndpointTraffic where latency > 100 --> endpointLatencyHigh
// number filter with '>' resolves to 'greaterMatch'; if unsupported for this source,
// use an equality/string filter that has a registered matcher:
// after
from EndpointTraffic where name like 'api%' --> endpointApiTraffic
Defensive patterns

Strategy: validation

Validate before calling

// Before generating, check the matcher type exists:
String type = mapOperatorToExpressionType(expr); // your mapping
if (!FilterMatchers.getRegisteredTypes().contains(type)) {
    throw new ConfigException("OAL filter uses unsupported matcher: " + type);
}

Try / catch

catch (IllegalArgumentException e) when starting OAP with custom OAL; wrap the OAL load so the message (which names the missing type) reaches the deploy log, then fix the .oal rule rather than catching in production code.

Prevention

When it happens

Trigger: An OAL script uses a filter such as 'from ServiceTraffic where name like ...' whose operator/value shape maps to an expression type (e.g. 'greaterMatch', 'inMatch') that has no registered matcher class; or a custom matcher class exists but lacks the registration annotation or has value() empty and its simple name was not uncapitalized as expected; or a typo in the generated expression-type string in MetricDefinitionEnricher.mapOperatorToExpressionType.

Common situations: Extending OAL with a new filter operator or a new matcher class without registering it; upgrading SkyWalking versions where matcher keys were renamed; hand-editing generated OAL code; using an OAL filter syntax on a source attribute whose type maps to a matcher that was never implemented (e.g. an array filter before inMatch existed).

Related errors

AI-assisted analysis of apache/skywalking@102af09b4a (2026-08-14). Data as JSON: /api/errors/99922f2dcdb07f03. Report an issue: GitHub.