apache/beam · error · IllegalArgumentException

JDBC type must be one of

Error message

JDBC type must be one of ${JDBC_DRIVER_MAP.keySet()}

What it means

When jdbcType is present, validate() checks it against JDBC_DRIVER_MAP (lowercased). An unrecognized type name means no built-in driver mapping exists, so the provider throws this IllegalArgumentException listing the valid keys.

Solutions

  1. Replace jdbcType with one of the map's keys exactly (lowercase), as listed in the exception message.
  2. For unsupported engines, set driverClassName and driverJars explicitly instead of jdbcType.
  3. Normalize user input with toLowerCase() before assigning jdbcType.

Example fix

// before
.setJdbcType("MariaDB")
// after
.setJdbcType("mysql") // or .setDriverClassName("org.mariadb.jdbc.Driver")
Defensive patterns

Strategy: validation

Validate before calling

Set<String> allowed = Set.of("mysql", "postgresql", "oracle", "mssql"); // JDBC_DRIVER_MAP keys
if (jdbcType != null && !allowed.contains(jdbcType.toLowerCase())) {
  throw new IllegalArgumentException("jdbcType must be one of " + allowed);
}

Try / catch

try {
  config.validate();
} catch (IllegalArgumentException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("JDBC type must be one of")) {
    throw new IllegalStateException("Unsupported jdbcType '" + jdbcType + "'; valid: " + e.getMessage(), e);
  }
  throw e;
}

Prevention

When it happens

Trigger: Setting jdbcType to a string not in JDBC_DRIVER_MAP.keySet() (e.g. 'postgres', 'aurora', 'MariaDB') while driverClassName is not set.

Common situations: Case/abbreviation mistakes, using a cloud-database brand name instead of the underlying engine type, or copy-pasting driver class names into the jdbcType field.

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/c436ed4aa696e196. Report an issue: GitHub.

Appendix: source

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

        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.");
      }
      // Reading with partitions only supports table argument.
      if (partitionColumnPresent && !locationPresent) {
        throw new IllegalArgumentException("Table must be specified to read with partitions.");
      }

View on GitHub (pinned to 12126d8942)