grpc/grpc-java · error · IllegalArgumentException

CEL expression references unknown function with overload IDs

Error message

CEL expression references unknown function with overload IDs:

What it means

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.

Source

Thrown at xds/src/main/java/io/grpc/xds/internal/matcher/CelCommon.java:116

              "CEL expression references unknown variable: " + ref.name());
        }
      } else if (!ref.overloadIds().isEmpty()) {
        String name = ref.name();
        if (name.isEmpty()) {
          boolean allowed = false;
          for (String id : ref.overloadIds()) {
            if (id.equals("add_string") || id.equals("add_list") || id.endsWith("_to_string")) {
              allowed = false;
              break;
            }
            if (ALLOWED_EXACT_OVERLOAD_IDS.contains(id)
                || ALLOWED_OVERLOAD_ID_PREFIX_PATTERN.matcher(id).matches()) {
              allowed = true;
              break;
            }
          }
          if (!allowed) {
            throw new IllegalArgumentException(
                "CEL expression references unknown function with overload IDs: "
                    + ref.overloadIds());
          }
        } else {
          // Standard conversion functions (like string(x)) are named in the AST.
          // We must explicitly reject 'string' here since it's disabled in the environment.
          if (name.equals("string")) {
            throw new IllegalArgumentException(
                "CEL expression references unknown function with overload IDs: "
                    + ref.overloadIds());
          }
          throw new IllegalArgumentException(
              "CEL expression references unsupported named function: " + name);
        }
      }
    }
  }
}

View on GitHub (pinned to 64daddc1f3)

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

Example fix

// before
CEL: request.headers['x-a'].matches('(?i)foo')
// after — use allowed constructs
CEL: request.headers['x-a'] == 'foo' || request.headers['x-a'] == 'FOO'

Defensive patterns

Strategy: try-catch

Validate before calling

// restrict to known-safe builtins
if (!Set.of("size","has","matches").containsAll(extractFunctionNames(celSource))) {
  throw new IllegalArgumentException("CEL uses disallowed function");
}

Try / catch

try {
  CelCommon.checkAllowedReferences(ast);
} catch (IllegalArgumentException e) {
  log.error("CEL function rejected: {}", e.getMessage());
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

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 grpc/grpc-java@64daddc1f3 (2026-09-08). Data as JSON: /api/errors/d477a253f61a24fc. Report an issue: GitHub.