apache/beam · error · IllegalArgumentException

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

Error message

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

What it means

If driverClassName is absent, the provider falls back to jdbcType which must be a key of JDBC_DRIVER_MAP (a fixed set of known database types). When neither driverClassName nor a recognized jdbcType is present, validate() throws this IllegalArgumentException.

Solutions

Use an exact key from JDBC_DRIVER_MAP in lowercase (e.g. 'postgresql', 'mysql', 'mssql', 'oracle').
Alternatively provide driverClassName + driverJars to bypass the jdbcType map.
Log/print JDBC_DRIVER_MAP.keySet() at config build time to pick a valid value.

Example fix

// before
builder().setJdbcType("postgres")
// after
builder().setJdbcType("postgresql") // or setDriverClassName("org.postgresql.Driver").setDriverJars(...)

Defensive patterns

Strategy: validation

Validate before calling

String t = config.getJdbcType();
if ((config.getDriverClassName() == null || config.getDriverClassName().isEmpty())
    && (t == null || t.isEmpty())) {
  throw new IllegalArgumentException("jdbcType or driverClassName required");
}

Try / catch

try {
  config.validate();
} catch (IllegalArgumentException e) {
  if (e.getMessage() != null && e.getMessage().contains("One of JDBC Driver class name or JDBC type")) {
    throw new IllegalStateException("Unknown jdbcType; use a JDBC_DRIVER_MAP key", e);
  }
  throw e;
}

Prevention

Normalize jdbcType with toLowerCase() before assignment.
Prefer explicit driverClassName+driverJars for less common engines.
Validate the value against the documented list of supported types in CI.

When it happens

Trigger: Calling validate()/from() with a config that has empty driverClassName and a jdbcType that is null/empty, or when the second check is reached with an unrecognized jdbcType (the sibling error 'JDBC type must be one of ...' covers non-null unknown values).

Common situations: Passing jdbcType values like 'postgres' or 'MySQL' with wrong casing/abbreviation not in the map while driverClassName is unset; omitting driver fields entirely.

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

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

Appendix: source

Thrown at sdks/java/io/jdbc/src/main/java/org/apache/beam/sdk/io/jdbc/JdbcReadSchemaTransformProvider.java:417

      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());
      }

      boolean readQueryPresent = (getReadQuery() != null && !"".equals(getReadQuery()));
      boolean locationPresent = (getLocation() != null && !"".equals(getLocation()));
      boolean partitionColumnPresent =
          (getPartitionColumn() != null && !"".equals(getPartitionColumn()));

      // If you specify a readQuery, it is to be used instead of a table.
      if (readQueryPresent && locationPresent) {
        throw new IllegalArgumentException("Query and Table are mutually exclusive configurations");
      }
      if (!readQueryPresent && !locationPresent) {
        throw new IllegalArgumentException("Either Query or Table must be specified.");

View on GitHub (pinned to 12126d8942)