apache/beam · error · IllegalArgumentException

Unrecognized dialect: + dialect.name()

Error message

Unrecognized dialect: + dialect.name()

What it means

parseSpannerType switches on the database Dialect (GOOGLE_SQL / POSTGRESQL); hitting the default branch means the Dialect enum value passed in is not recognized, and it throws IllegalArgumentException("Unrecognized dialect: " + dialect.name()). Since Dialect has only two values, this indicates a corrupt/extended enum or a version mismatch.

Source

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

            Type itemType = parseSpannerType(spannerArrayType, dialect);
            return Type.array(itemType);
          }
          type = POSTGRES_TYPE_MAP.get(spannerType);
          if (type != null) {
            return type;
          }
          if (spannerType.startsWith("CHARACTER VARYING")) {
            return Type.string();
          }
          if (spannerType.startsWith("NUMERIC")) {
            return Type.pgNumeric();
          }
          if (spannerType.startsWith("JSONB")) {
            return Type.pgJsonb();
          }
          throw new IllegalArgumentException("Unknown spanner type " + spannerType);
        default:
          throw new IllegalArgumentException("Unrecognized dialect: " + dialect.name());
      }
    }
  }
}

View on GitHub (pinned to 12126d8942)

Solutions

1. Check the dialect name printed in the message and ensure only SpannerSchema.Dialect GOOGLE_SQL or POSTGRESQL is used.
2. Resolve duplicate Beam IO jar versions on the classpath (dependency:tree, exclusions).
3. Upgrade Beam so both the Dialect enum and SpannerSchema come from the same version.

Example fix

// before
SpannerSchema.create(schema, Dialect.valueOf("MONGODB"));
// after
SpannerSchema.create(schema, Dialect.GOOGLE_SQL);

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

try { SpannerSchema.create(s, dialect); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Unrecognized dialect")) { /* fix classpath/dialect source */ } throw e; }

When it happens

Trigger: Calling SpannerSchema.create(spannerSchema, dialect) or itemType with a Dialect value outside {GOOGLE_SQL, POSTGRESQL} — practically only via a shading/relocation conflict or a custom Dialect enum from a different Beam version on the classpath.

Common situations: Classpath pollution with multiple beam-sdks-java-io-google-cloud-platform versions; custom forks adding a Dialect constant passed into stock SpannerSchema.

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

• Unknown failure mode + failureMode
• Cannot merge schemas with different numbers of fields. schem
• Unsupported type of %s: %s
• typehint for arg type %s already exists
• Unexpected expansion service address. Expected to be in the

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