apache/beam · error · IllegalArgumentException

One of JDBC Driver class name or JDBC type must be specified

Error message

One of JDBC Driver class name or JDBC type must be specified.

What it means

When no explicit driverClassName is given, the provider must resolve the driver from a known jdbcType. If neither is present it throws this IllegalArgumentException, telling the user to supply one of the two.

Source

Thrown at sdks/java/io/jdbc/src/main/java/org/apache/beam/sdk/io/jdbc/JdbcWriteSchemaTransformProvider.java:402

      validate("");
    }

    public void validate(String jdbcType) throws IllegalArgumentException {
      if (Strings.isNullOrEmpty(getJdbcUrl())) {
        throw new IllegalArgumentException("JDBC URL cannot be blank");
      }

      jdbcType = !Strings.isNullOrEmpty(jdbcType) ? jdbcType : getJdbcType();

      boolean driverClassNamePresent = !Strings.isNullOrEmpty(getDriverClassName());
      boolean driverJarsPresent = !Strings.isNullOrEmpty(getDriverJars());
      boolean jdbcTypePresent = !Strings.isNullOrEmpty(jdbcType);
      if (!driverClassNamePresent && !driverJarsPresent && !jdbcTypePresent) {
        throw new IllegalArgumentException(
            "If JDBC type is not specified, then Driver Class Name and Driver Jars must be specified.");
      }
      if (!driverClassNamePresent && !jdbcTypePresent) {
        throw new IllegalArgumentException(
            "One of JDBC Driver class name or JDBC type must be specified.");
      }
      if (jdbcTypePresent
          && !JDBC_DRIVER_MAP.containsKey(Objects.requireNonNull(jdbcType).toLowerCase())) {
        throw new IllegalArgumentException(
            "JDBC type must be one of " + JDBC_DRIVER_MAP.keySet() + " but was " + jdbcType);
      }

      boolean writeStatementPresent =
          (getWriteStatement() != null && !"".equals(getWriteStatement()));
      boolean locationPresent = (getLocation() != null && !"".equals(getLocation()));

      if (writeStatementPresent && locationPresent) {
        throw new IllegalArgumentException(
            "Write Statement and Table are mutually exclusive configurations");
      }
      if (!writeStatementPresent && !locationPresent) {
        throw new IllegalArgumentException("Either Write Statement or Table must be set.");

View on GitHub (pinned to 12126d8942)

Solutions

1. Set jdbcType (e.g. "postgres", "mysql", "mssql", "oracle")
2. Or set driverClassName to the fully qualified driver class
3. Combine with driverJars for drivers not bundled with Beam

Example fix

// before
builder().setJdbcUrl(url).setDriverJars("gs://bucket/postgres.jar").build();
// after
builder().setJdbcUrl(url).setDriverClassName("org.postgresql.Driver").setDriverJars("gs://bucket/postgres.jar").build();

if (Strings.isNullOrEmpty(cfg.getJdbcType()) && Strings.isNullOrEmpty(cfg.getDriverClassName())) {
  throw new IllegalArgumentException("One of jdbcType or driverClassName must be set");
}

try {
  config.validate();
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("One of JDBC Driver class name or JDBC type must be specified")) {
    LOG.error("Set jdbcType or driverClassName; driverJars alone is not enough");
  }
  throw e;
}

When it happens

Trigger: Calling validate() with driverClassName empty AND jdbcType empty (driverJars alone does not satisfy this check).

Common situations: Users assuming driverJars alone is enough; omitting both driver fields when migrating from the older JdbcIO write API to the schema-transform provider.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• If JDBC type is not specified, then Driver Class Name and Dr
• JDBC URL cannot be blank
• JDBC type must be one of ${JDBC_DRIVER_MAP.keySet()} but was
• Write Statement and Table are mutually exclusive configurati
• Either Write Statement or Table must be set.

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