{"record":{"id":"aa7bbdf8c338756f","repo":"apache/beam","slug":"received-unknown-sql-dialect-s-known-dialects-s","errorCode":null,"errorMessage":"Received unknown SQL Dialect '%s'. Known dialects: %s","messagePattern":"Received unknown SQL Dialect '(.+?)'\\. Known dialects: (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/extensions/sql/expansion-service/src/main/java/org/apache/beam/sdk/extensions/sql/expansion/ExternalSqlTransformRegistrar.java","lineNumber":75,"sourceCode":"    public void setDialect(@Nullable String dialect) {\n      this.dialect = dialect;\n    }\n\n    public void setDdl(@Nullable String ddl) {\n      this.ddl = ddl;\n    }\n  }\n\n  private static class Builder\n      implements ExternalTransformBuilder<Configuration, PInput, PCollection<Row>> {\n    @Override\n    public PTransform<PInput, PCollection<Row>> buildExternal(Configuration configuration) {\n      SqlTransform transform = SqlTransform.query(configuration.query);\n      if (configuration.dialect != null) {\n        Class<? extends QueryPlanner> queryPlanner =\n            DIALECTS.get(configuration.dialect.toLowerCase());\n        if (queryPlanner == null) {\n          throw new IllegalArgumentException(\n              String.format(\n                  \"Received unknown SQL Dialect '%s'. Known dialects: %s\",\n                  configuration.dialect, DIALECTS.keySet()));\n        }\n        transform = transform.withQueryPlannerClass(queryPlanner);\n      }\n      // Add any DDL string\n      if (configuration.ddl != null) {\n        transform = transform.withDdlString(configuration.ddl);\n      }\n      return transform;\n    }\n  }\n}\n","sourceCodeStart":57,"sourceCodeEnd":90,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/extensions/sql/expansion-service/src/main/java/org/apache/beam/sdk/extensions/sql/expansion/ExternalSqlTransformRegistrar.java#L57-L90","documentation":"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.","triggerScenarios":"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'.","commonSituations":"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.","solutions":["Use one of the dialects listed in the error message's known-dialects set (e.g. 'calcite', 'zetasql' if registered).","Fix typos in the dialect name in your expansion configuration.","If a dialect is missing, register a custom planner via code instead of the expansion service, or upgrade Beam."],"exampleFix":"// before\nConfiguration config = Configuration.of(\"query\", \"SELECT 1\", \"dialect\", \"mysql\");\n// after\nConfiguration config = Configuration.of(\"query\", \"SELECT 1\", \"dialect\", \"calcite\");","handlingStrategy":"validation","validationCode":"// before invoking the expansion service\nif (dialect != null && !KNOWN_DIALECTS.contains(dialect.toLowerCase())) {\n  throw new IllegalArgumentException(\"Unknown dialect \" + dialect + \", known: \" + KNOWN_DIALECTS);\n}","typeGuard":null,"tryCatchPattern":"try {\n  transform = registrar.buildExternal(configuration);\n} catch (IllegalArgumentException e) {\n  if (e.getMessage().contains(\"unknown SQL Dialect\")) {\n    // fall back to default (no dialect => Calcite planner)\n  }\n}","preventionTips":["Use only dialect names listed in the error's known-dialects set.","Omit the dialect field entirely to use the default Calcite planner.","Confirm dialect availability in your Beam version before cross-language expansion."],"tags":["java","beam-sql","expansion-service","dialect","cross-language"],"backgroundTag":"invalid-enum-value","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}