What causes "JDBC URL cannot be blank" in apache/beam?

Set jdbcUrl in the configuration, e.g. jdbc:postgresql://host:5432/db

apache/beam · error · IllegalArgumentException

JDBC URL cannot be blank

Error message

JDBC URL cannot be blank

What it means

Validation inside JdbcWriteSchemaTransformProvider's configuration that refuses to run a JDBC write when the jdbcUrl is null or empty (Guava Strings.isNullOrEmpty). A blank URL gives the driver nothing to connect to, so it fails fast with IllegalArgumentException.

Source

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

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

    @SchemaFieldDescription("SQL query used to insert records into the JDBC sink.")
    @Nullable
    public abstract String getWriteStatement();

    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(

View on GitHub (pinned to 12126d8942)

Solutions

Set jdbcUrl in the configuration, e.g. jdbc:postgresql://host:5432/db
Verify the config value actually resolves (log or print the built configuration before validate())
If reading from env/config file, check the variable is exported/non-empty at submit time

Example fix

// before
JdbcWriteSchemaTransformProvider.Config cfg = builder().setDriverClassName("org.postgresql.Driver").build();
// after
JdbcWriteSchemaTransformProvider.Config cfg = builder()
    .setJdbcUrl("jdbc:postgresql://localhost:5432/mydb")
    .setDriverClassName("org.postgresql.Driver").build();

Defensive patterns

Strategy: validation

Validate before calling

import org.apache.beam.vendor.guava.v32_1_2_jre.com.google.common.base.Strings;
if (Strings.isNullOrEmpty(cfg.getJdbcUrl())) {
  throw new IllegalArgumentException("jdbcUrl must be set before validate()");
}

Try / catch

try {
  config.validate();
} catch (IllegalArgumentException e) {
  if (e.getMessage().equals("JDBC URL cannot be blank")) {
    LOG.error("Set jdbcUrl in the schema-transform configuration");
  }
  throw e;
}

Prevention

Always set jdbcUrl first when building the configuration
If the URL comes from env/config, assert non-empty at pipeline-argument parsing time
Validate config immediately after building, before expansion

When it happens

Trigger: Calling validate() on JdbcWriteSchemaTransformConfiguration without setting jdbcUrl, or setting it to ""; building the config from external parameters where the URL key is missing or empty.

Common situations: Missing or misnamed config parameter in a YAML/CLI pipeline submission; environment variable not expanded; copy-pasted config where jdbcUrl line was omitted.

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

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