apache/druid · error · ExpressionValidationException

first argument must be a valid COMPLEX type name, got unknow

Error message

first argument must be a valid COMPLEX type name, got unknown COMPLEX type [%s]

What it means

After the first argument of complex_decode_base64 is confirmed to be a constant string, it is resolved via ExpressionTypeFactory.ofComplex and its type strategy is fetched. If the named complex type is unknown (no registered strategy), this validationFailed is thrown listing the invalid COMPLEX type name.

Source

Thrown at processing/src/main/java/org/apache/druid/math/expr/BuiltInExprMacros.java:88

          );
        }
        if (arg0.isNullLiteral()) {
          throw validationFailed("first argument must be constant STRING expression containing a valid complex type name but got NULL instead");
        }
        final Object literal = arg0.getLiteralValue();
        if (!(literal instanceof String)) {
          throw validationFailed(
              "first argument must be constant STRING expression containing a valid complex type name but got '%s' instead",
              arg0.getLiteralValue()
          );
        }

        this.complexType = ExpressionTypeFactory.getInstance().ofComplex((String) literal);
        try {
          this.typeStrategy = complexType.getStrategy();
        }
        catch (IllegalArgumentException illegal) {
          throw validationFailed(
              "first argument must be a valid COMPLEX type name, got unknown COMPLEX type [%s]",
              complexType.asTypeString()
          );
        }
      }

      @Override
      public ExprEval<?> eval(ObjectBinding bindings)
      {
        ExprEval<?> toDecode = args.get(1).eval(bindings);
        if (toDecode.value() == null) {
          return ExprEval.ofComplex(complexType, null);
        }
        final Object serializedValue = toDecode.value();
        final byte[] base64;
        if (serializedValue instanceof String) {
          base64 = StringUtils.decodeBase64String(toDecode.asString());
        } else if (serializedValue instanceof byte[]) {

View on GitHub (pinned to 9b90983fd2)

Solutions

  1. Verify the exact registered complex type name (e.g. via available types/segment metadata).
  2. Load the Druid extension that registers the complex type (e.g. druid-datasketches) on all relevant services.
  3. Fix typos in the type name string.
  4. Check druid.extension.load list in runtime.properties.

Example fix

// before
complex_decode_base64('mySketchTypo', base64_col)
// after
complex_decode_base64('hyperUnique', base64_col)  // or load the extension providing the correct type
Defensive patterns

Strategy: validation

When it happens

Trigger: Calling complex_decode_base64('someUnknownType', col) where the string is not a registered complex type name in the cluster (e.g. missing an extension that provides the complex type serializer).

Common situations: Extension not loaded on the cluster (e.g. druid-datasketches types used without the extension); typo in the type name; type exists on one broker/service but not another after a version change.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/4b4374b8444c942a. Report an issue: GitHub.