{"record":{"id":"d477a253f61a24fc","repo":"grpc/grpc-java","slug":"cel-expression-references-unknown-function-with-ov","errorCode":null,"errorMessage":"CEL expression references unknown function with overload IDs: ","messagePattern":"CEL expression references unknown function with overload IDs: ","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"xds/src/main/java/io/grpc/xds/internal/matcher/CelCommon.java","lineNumber":116,"sourceCode":"              \"CEL expression references unknown variable: \" + ref.name());\n        }\n      } else if (!ref.overloadIds().isEmpty()) {\n        String name = ref.name();\n        if (name.isEmpty()) {\n          boolean allowed = false;\n          for (String id : ref.overloadIds()) {\n            if (id.equals(\"add_string\") || id.equals(\"add_list\") || id.endsWith(\"_to_string\")) {\n              allowed = false;\n              break;\n            }\n            if (ALLOWED_EXACT_OVERLOAD_IDS.contains(id)\n                || ALLOWED_OVERLOAD_ID_PREFIX_PATTERN.matcher(id).matches()) {\n              allowed = true;\n              break;\n            }\n          }\n          if (!allowed) {\n            throw new IllegalArgumentException(\n                \"CEL expression references unknown function with overload IDs: \"\n                    + ref.overloadIds());\n          }\n        } else {\n          // Standard conversion functions (like string(x)) are named in the AST.\n          // We must explicitly reject 'string' here since it's disabled in the environment.\n          if (name.equals(\"string\")) {\n            throw new IllegalArgumentException(\n                \"CEL expression references unknown function with overload IDs: \"\n                    + ref.overloadIds());\n          }\n          throw new IllegalArgumentException(\n              \"CEL expression references unsupported named function: \" + name);\n        }\n      }\n    }\n  }\n}","sourceCodeStart":98,"sourceCodeEnd":134,"githubUrl":"https://github.com/grpc/grpc-java/blob/64daddc1f3d1975670f769f3e97bde8b2ba32d25/xds/src/main/java/io/grpc/xds/internal/matcher/CelCommon.java#L98-L134","documentation":"checkAllowedReferences also validates function references in CEL ASTs. Functions are identified by overload IDs; each overload ID must match the allowlist (standard library overload patterns / allowed prefix pattern). When none of the overload IDs are allowed, this IllegalArgumentException is thrown, blocking CEL expressions that call unavailable functions.","triggerScenarios":"A CEL expression uses a function whose overload IDs do not match the allowlist patterns — e.g., custom extensions, or standard functions from a broader CEL environment that this xDS matcher does not permit — and the reference has an empty/unknown name so only overload IDs are checked.","commonSituations":"Copying CEL from Envoy or other CEL-using systems with functions enabled there; using newer CEL library overloads not covered by the allowlist pattern; expressions compiled against a different CelEnvironment.","solutions":["Rewrite the expression using only functions/overloads permitted by the xDS CEL environment (string matching, size, basic comparisons)","Remove unsupported function calls and compute values outside CEL where possible","Check ref.overloadIds() against ALLOWED_OVERLOAD_ID_PREFIX_PATTERN to see why it was rejected","Ensure the expression is compiled with this library's CelEnvironment, not a broader one"],"exampleFix":"// before\nCEL: request.headers['x-a'].matches('(?i)foo')\n// after — use allowed constructs\nCEL: request.headers['x-a'] == 'foo' || request.headers['x-a'] == 'FOO'","handlingStrategy":"try-catch","validationCode":"// restrict to known-safe builtins\nif (!Set.of(\"size\",\"has\",\"matches\").containsAll(extractFunctionNames(celSource))) {\n  throw new IllegalArgumentException(\"CEL uses disallowed function\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  CelCommon.checkAllowedReferences(ast);\n} catch (IllegalArgumentException e) {\n  log.error(\"CEL function rejected: {}\", e.getMessage());\n}","preventionTips":["Use only the xDS matcher's declared CEL functions","Compile with this library's CelEnvironment, not a broader one","Avoid custom/extension functions from other CEL deployments","Review AST reference maps when porting expressions"],"tags":["grpc","xds","cel","function-allowlist"],"backgroundTag":"invalid-argument-value","analyzedSha":"64daddc1f3d1975670f769f3e97bde8b2ba32d25","analyzedAt":"2026-09-08T06:14:57.704Z","contentChangedAt":"2026-09-08T06:14:57.704Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}