apache/beam · error · IllegalArgumentException

JDBC URL cannot be blank

Error message

JDBC URL cannot be blank

What it means

JdbcReadSchemaTransformProvider's configuration validator requires a non-empty JDBC URL. Before any other checks, validate() uses Strings.isNullOrEmpty(getJdbcUrl()) and throws IllegalArgumentException if the URL is blank. This fails fast at pipeline construction instead of at runtime connection time.

Solutions

1. Set the jdbcUrl field on the configuration, e.g. jdbc:mysql://host:3306/db.
2. If loading from config file/environment, check the value is populated before building the transform.
3. Wrap validate() in a config pre-check that surfaces which required field is missing.

Example fix

// before
JdbcReadSchemaTransformProvider.JdbcReadSchemaTransformConfiguration.builder().setReadQuery(q).build()
// after
...builder().setReadQuery(q).setJdbcUrl("jdbc:postgresql://localhost:5432/mydb").build()

if (config.getJdbcUrl() == null || config.getJdbcUrl().isBlank()) {
  throw new IllegalArgumentException("jdbcUrl is required, e.g. jdbc:postgresql://host:5432/db");
}

try {
  config.validate();
} catch (IllegalArgumentException e) {
  if ("JDBC URL cannot be blank".equals(e.getMessage())) {
    throw new IllegalStateException("Missing jdbcUrl in transform config", e);
  }
  throw e;
}

When it happens

Trigger: Building a JdbcReadSchemaTransform (including SqlServerReadSchemaTransform) via from()/validate() without setting jdbcUrl, or setting it to null/empty string.

Common situations: Constructing the transform map/config programmatically and forgetting the jdbcUrl key, YAML/JSON config missing the field, or a template variable (e.g. ${DB_URL}) resolving to empty.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• Either Query or Table must be specified.
• Query and Table are mutually exclusive configurations
• Batch size is too large! It should be smaller or equal than
• Column delimiter should be set if headers are present.
• Column headers should be supplied when delimiter is present.

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

Appendix: source

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

    @Nullable
    public abstract String getReadQuery();

    @SchemaFieldDescription(
        "Secret Manager to use for fetching secret values. Available options: 'GoogleCloudSecretManager', 'GoogleCloudHsmGeneratedSecretManager'. If not set, no secret manager is used and the password is treated as a plain password.")
    @Nullable
    public abstract String getSecretManager();

    @SchemaFieldDescription("Username for the JDBC source.")
    @Nullable
    public abstract String getUsername();

    public void validate() {
      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());

View on GitHub (pinned to 12126d8942)