apache/beam · error · IllegalArgumentException

Received unknown SQL Dialect '%s'. Known dialects: %s

Error message

Received unknown SQL Dialect '%s'. Known dialects: %s

What it means

ExternalSqlTransformRegistrar.buildExternal resolves the configured SQL dialect name against its DIALECTS map of known dialect-to-planner-class entries. If configuration.dialect is set but does not match any key (case-insensitively), the registrar throws IllegalArgumentException listing the known dialects, so expansion fails fast with a clear message.

Source

Thrown at sdks/java/extensions/sql/expansion-service/src/main/java/org/apache/beam/sdk/extensions/sql/expansion/ExternalSqlTransformRegistrar.java:75

    public void setDialect(@Nullable String dialect) {
      this.dialect = dialect;
    }

    public void setDdl(@Nullable String ddl) {
      this.ddl = ddl;
    }
  }

  private static class Builder
      implements ExternalTransformBuilder<Configuration, PInput, PCollection<Row>> {
    @Override
    public PTransform<PInput, PCollection<Row>> buildExternal(Configuration configuration) {
      SqlTransform transform = SqlTransform.query(configuration.query);
      if (configuration.dialect != null) {
        Class<? extends QueryPlanner> queryPlanner =
            DIALECTS.get(configuration.dialect.toLowerCase());
        if (queryPlanner == null) {
          throw new IllegalArgumentException(
              String.format(
                  "Received unknown SQL Dialect '%s'. Known dialects: %s",
                  configuration.dialect, DIALECTS.keySet()));
        }
        transform = transform.withQueryPlannerClass(queryPlanner);
      }
      // Add any DDL string
      if (configuration.ddl != null) {
        transform = transform.withDdlString(configuration.ddl);
      }
      return transform;
    }
  }
}

View on GitHub (pinned to 12126d8942)

Solutions

1. Use one of the dialects listed in the error message's known-dialects set (e.g. 'calcite', 'zetasql' if registered).
2. Fix typos in the dialect name in your expansion configuration.
3. If a dialect is missing, register a custom planner via code instead of the expansion service, or upgrade Beam.

Example fix

// before
Configuration config = Configuration.of("query", "SELECT 1", "dialect", "mysql");
// after
Configuration config = Configuration.of("query", "SELECT 1", "dialect", "calcite");

// before invoking the expansion service
if (dialect != null && !KNOWN_DIALECTS.contains(dialect.toLowerCase())) {
  throw new IllegalArgumentException("Unknown dialect " + dialect + ", known: " + KNOWN_DIALECTS);
}

try {
  transform = registrar.buildExternal(configuration);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("unknown SQL Dialect")) {
    // fall back to default (no dialect => Calcite planner)
  }
}

When it happens

Trigger: Constructing the external SqlTransform (cross-language expansion via the Beam SQL expansion service) with a Configuration whose 'dialect' field is a string not present in DIALECTS, e.g. 'mysql', 'zetaSQL', or a typo like 'calciet'.

Common situations: Python pipelines specifying an unsupported dialect when using the Java expansion service; dialect names valid in other engines but not registered in this Beam version; misspelled or wrong-case handled only if key absent — casing is handled via toLowerCase, so truly unknown names fail.

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

• expansion service error: %s
• Could not find coder for URN " + urn
• Timing number 0b" + timingNumber.toString(2) + " has more th
• No proto encoding for PaneInfoCoder, always part of Windowed
• ${response.error}

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/aa7bbdf8c338756f. Report an issue: GitHub.