{"record":{"id":"99922f2dcdb07f03","repo":"apache/skywalking","slug":"filter-expression-not-found","errorCode":null,"errorMessage":"filter expression [{}] not found","messagePattern":"filter expression \\[(.+?)\\] not found","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"oap-server/oal-rt/src/main/java/org/apache/skywalking/oal/v2/metadata/FilterMatchers.java","lineNumber":84,"sourceCode":"                    matchersKeyedByType.put(defaultTypeName, new MatcherInfo(clazz, false));\n                }\n            }\n\n            if (booleanFilterMatcher != null) {\n                for (final String type : booleanFilterMatcher.value()) {\n                    matchersKeyedByType.put(type, new MatcherInfo(clazz, true));\n                }\n                if (booleanFilterMatcher.value().length == 0) {\n                    final String defaultTypeName = StringUtils.uncapitalize(clazz.getSimpleName());\n                    matchersKeyedByType.put(defaultTypeName, new MatcherInfo(clazz, true));\n                }\n            }\n        }\n    }\n\n    public MatcherInfo find(final String type) {\n        if (!matchersKeyedByType.containsKey(type)) {\n            throw new IllegalArgumentException(\"filter expression [\" + type + \"] not found\");\n        }\n        return matchersKeyedByType.get(type);\n    }\n\n    @Getter\n    @AllArgsConstructor\n    public static class MatcherInfo {\n        private final Class<?> matcher;\n        private final boolean isBooleanType;\n    }\n}\n","sourceCodeStart":66,"sourceCodeEnd":96,"githubUrl":"https://github.com/apache/skywalking/blob/102af09b4a56064e22050dded10e2c52e490d040/oap-server/oal-rt/src/main/java/org/apache/skywalking/oal/v2/metadata/FilterMatchers.java#L66-L96","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["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","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","Rewrite the OAL filter to use an operator/value-type combination that maps to an existing matcher (see MetricDefinitionEnricher.mapOperatorToExpressionType for the supported mappings)","Verify no typo in the expression-type string if you modified codegen: the key must exactly match the annotation value or StringUtils.uncapitalize(SimpleName)"],"exampleFix":"// before (OAL)\nfrom EndpointTraffic where latency > 100 --> endpointLatencyHigh\n// number filter with '>' resolves to 'greaterMatch'; if unsupported for this source,\n// use an equality/string filter that has a registered matcher:\n// after\nfrom EndpointTraffic where name like 'api%' --> endpointApiTraffic","handlingStrategy":"validation","validationCode":"// Before generating, check the matcher type exists:\nString type = mapOperatorToExpressionType(expr); // your mapping\nif (!FilterMatchers.getRegisteredTypes().contains(type)) {\n    throw new ConfigException(\"OAL filter uses unsupported matcher: \" + type);\n}","typeGuard":null,"tryCatchPattern":"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.","preventionTips":["Keep a checked-in list of supported filter operators per value type and lint OAL files against it in CI","When adding matchers, add a unit test asserting FilterMatchers.find() resolves every type string your enricher can emit"],"tags":["oal","code-generation","filter","configuration"],"backgroundTag":null,"analyzedSha":"102af09b4a56064e22050dded10e2c52e490d040","analyzedAt":"2026-08-14T10:47:52.647Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}