apache/beam · error · IllegalArgumentException

Unrecognized dialect: + dialect.name()

Error message

Unrecognized dialect: + dialect.name()

What it means

ReadSpannerSchema builds information-schema SQL per Spanner dialect (GOOGLE_STANDARD_SQL or POSTGRESQL). readTableInfo() throws IllegalArgumentException when the configured Dialect enum value has no corresponding SQL template, meaning the connector does not support the dialect passed in. It indicates an unsupported-dialect configuration rather than a data problem.

Source

Thrown at sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/spanner/ReadSpannerSchema.java:172

                + "    c.table_name"
                + "  , c.column_name"
                + "  , c.spanner_type"
                + "  , (1 + COALESCE(t.indices, 0)) AS cells_mutated"
                + "  FROM ("
                + "    SELECT c.table_name, c.column_name, c.spanner_type, c.ordinal_position"
                + "      FROM information_schema.columns as c"
                + "      WHERE c.table_schema='public') AS c"
                + "  LEFT OUTER JOIN ("
                + "    SELECT t.table_name, t.column_name, COUNT(*) AS indices"
                + "      FROM information_schema.index_columns AS t "
                + "      WHERE t.index_name != 'PRIMARY_KEY'"
                + "      AND t.table_schema='public'"
                + "      GROUP BY t.table_name, t.column_name) AS t"
                + "  USING (table_name, column_name)"
                + "  ORDER BY c.table_name, c.ordinal_position";
        break;
      default:
        throw new IllegalArgumentException("Unrecognized dialect: " + dialect.name());
    }
    return tx.executeQuery(Statement.of(statement));
  }

  private ResultSet readPrimaryKeyInfo(ReadOnlyTransaction tx, Dialect dialect) {
    String statement = "";
    switch (dialect) {
      case GOOGLE_STANDARD_SQL:
        statement =
            "SELECT t.table_name, t.column_name, t.column_ordering"
                + " FROM information_schema.index_columns AS t "
                + " WHERE t.index_name = 'PRIMARY_KEY' AND t.table_catalog = ''"
                + " AND t.table_schema = ''"
                + " ORDER BY t.table_name, t.ordinal_position";
        break;
      case POSTGRESQL:
        statement =
            "SELECT t.table_name, t.column_name, t.column_ordering"

View on GitHub (pinned to 12126d8942)

Solutions

1. Upgrade the Beam google-cloud-platform SDK to a version that supports your database dialect
2. Verify the Spanner database was created with a supported dialect (standard SQL or PostgreSQL)
3. Check how Dialect is resolved for your SpannerConfig/database and ensure it matches a supported value
4. If on a custom build, add a case for the dialect in readTableInfo with the appropriate information-schema query

Example fix

// before
.withDialect(Dialect.GOOGLE_STANDARD_SQL_UNSUPPORTED_NEW)
// after
.withDialect(Dialect.GOOGLE_STANDARD_SQL)

if (dialect != Dialect.GOOGLE_STANDARD_SQL && dialect != Dialect.POSTGRESQL) { throw new IllegalArgumentException("Unsupported dialect: " + dialect); }

try { schema.read(tx, dialect); } catch (IllegalArgumentException e) { LOG.error("Unsupported Spanner dialect: {}", e.getMessage()); }

When it happens

Trigger: Running SpannerIO read pipelines against a database whose Dialect resolves to an enum value not covered by the switch in readTableInfo (e.g. a newly added dialect enum the connector version does not handle).

Common situations: Pointing the connector at a newer Spanner database dialect with an older Beam release; a null/odd Dialect returned from spannerConfig; copying code that hardcodes a Dialect constant unsupported by this code path.

Related errors

• Experimental host can only be used with instance id: + EXPER
• Failed to parse DirectedReadOptions from string: + directedR
• Unrecognized dialect: + dialect.name()
• MetadataInstance can't be empty
• MetadataDatabase can't be empty

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