apache/druid · error · IllegalArgumentException

Invalid URL format for PostgreSQL: [%s]

Error message

Invalid URL format for PostgreSQL: [%s]

What it means

tryParsePostgresConnectionUri invokes the pgJDBC driver's internal parseURL method reflectively; it returns null when the connection URI is not a valid PostgreSQL URL. Druid converts that null into this IllegalArgumentException showing the offending URI.

Source

Thrown at processing/src/main/java/org/apache/druid/utils/ConnectionUriUtils.java:193

        // no special handling for class not found because postgres driver is in distribution and should be available.
        throw new RuntimeException(otherPostgres);
      }
    } else {
      if (!allowUnknown) {
        throw new IAE("Unknown JDBC connection scheme: %s", connectionUri.split(":")[1]);
      }
      return Collections.emptySet();
    }
  }

  public static Set<String> tryParsePostgresConnectionUri(String connectionUri)
      throws ClassNotFoundException, NoSuchMethodException, InvocationTargetException, IllegalAccessException
  {
    Class<?> driverClass = Class.forName(POSTGRES_DRIVER);
    Method parseUrl = driverClass.getMethod("parseURL", String.class, Properties.class);
    Properties properties = (Properties) parseUrl.invoke(null, connectionUri, null);
    if (properties == null) {
      throw new IAE("Invalid URL format for PostgreSQL: [%s]", connectionUri);
    }
    Set<String> keys = Sets.newHashSetWithExpectedSize(properties.size());
    properties.forEach((k, v) -> keys.add((String) k));
    return keys;
  }

  public static Set<String> tryParseMySqlConnectionUri(String connectionUri)
      throws ClassNotFoundException, NoSuchMethodException, IllegalAccessException,
             InvocationTargetException
  {
    Class<?> connectionUrlClass = Class.forName(MYSQL_CONNECTION_URL);
    Method isConnectionStringSupported = connectionUrlClass.getMethod("acceptsUrl", String.class);
    if (!(boolean) isConnectionStringSupported.invoke(connectionUrlClass, connectionUri)) {
      throw new IAE("Invalid URL format for MySQL: [%s]", connectionUri);
    }
    Method getConnectionUrlInstanceMethod = connectionUrlClass.getMethod("getConnectionUrlInstance", String.class, Properties.class);
    Object conUrl = getConnectionUrlInstanceMethod.invoke(connectionUrlClass, connectionUri, null);
    Method getHostsList = connectionUrlClass.getMethod("getHostsList");

View on GitHub (pinned to 9b90983fd2)

Solutions

  1. Correct the URI to the form jdbc:postgresql://host:port/database?params per pgJDBC docs.
  2. Use the correct scheme jdbc:postgresql: (not jdbc:postgres:).
  3. Trim whitespace and stray characters from the configured URI.
  4. Pre-validate the URI with a regex/startsWith check before calling tryParseJdbcUriParameters.

Example fix

// before
String uri = "jdbc:postgres://localhost:5432/druid"; // invalid scheme
Set<String> keys = tryParsePostgresConnectionUri(uri);
// after
String uri = "jdbc:postgresql://localhost:5432/druid";
Set<String> keys = tryParsePostgresConnectionUri(uri);
Defensive patterns

Strategy: validation

Validate before calling

static boolean looksLikePostgresUri(String uri) {
  return uri != null && uri.startsWith("jdbc:postgresql://");
}

Try / catch

try {
  params = ConnectionUriUtils.tryParseJdbcUriParameters(uri, false);
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Invalid URL format for PostgreSQL")) {
    log.error("Bad PostgreSQL URI, expected jdbc:postgresql://host:port/db: " + uri);
  }
  throw e;
}

Prevention

When it happens

Trigger: Passing a string the pgJDBC parser rejects: missing jdbc:postgresql: prefix, malformed host/port/components, or a URI for a different database passed into the postgres parsing path.

Common situations: Typo'd schemes like jdbc:postgres:... (missing 'ql'), config values copied with extra characters or whitespace, and code paths that route non-postgres URIs into the postgres parser.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/89af769c3792b6e2. Report an issue: GitHub.