apache/druid · error · IllegalArgumentException

Unknown JDBC connection scheme: %s

Error message

Unknown JDBC connection scheme: %s

What it means

tryParseJdbcUriParameters only knows how to parse mysql: and postgresql: JDBC schemes. For any other scheme (e.g. jdbc:h2:, jdbc:oracle:) it throws this IllegalArgumentException with the offending scheme, unless the caller set allowUnknown=true, in which case it returns an empty set.

Source

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

        throw iaeMaria2x;
      }
      catch (Throwable otherMaria2x) {
        throw new RuntimeException(otherMaria2x);
      }
    } else if (connectionUri.startsWith(POSTGRES_PREFIX)) {
      try {
        return tryParsePostgresConnectionUri(connectionUri);
      }
      catch (IllegalArgumentException iaePostgres) {
        throw iaePostgres;
      }
      catch (Throwable otherPostgres) {
        // 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;
  }

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Only call tryParseJdbcUriParameters for mysql/postgresql URIs, or pass allowUnknown=true if an empty parameter set is acceptable.
2. Fix the JDBC URI scheme typo (jdbc:postgresql:... for Postgres).
3. Add explicit handling/whitelisting for your custom scheme before invoking the parser.
4. Validate the URI scheme before parsing: check uri.startsWith("jdbc:mysql:") || uri.startsWith("jdbc:postgresql:").

Example fix

// before
Set<String> params = ConnectionUriUtils.tryParseJdbcUriParameters("jdbc:h2:mem:test", false);
// after
if (uri.startsWith("jdbc:mysql:") || uri.startsWith("jdbc:postgresql:")) {
  Set<String> params = ConnectionUriUtils.tryParseJdbcUriParameters(uri, false);
} else {
  Set<String> params = Collections.emptySet();
}

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

static String extractScheme(String uri) {
  String[] parts = uri.split(":");
  return parts.length > 1 ? parts[1] : null;
}

try {
  params = ConnectionUriUtils.tryParseJdbcUriParameters(uri, false);
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("Unknown JDBC connection scheme")) {
    // unsupported scheme: fall back to empty params or route elsewhere
    params = Collections.emptySet();
  } else {
    throw e;
  }
}

When it happens

Trigger: Calling tryParseJdbcUriParameters with a URI whose second token (uri.split(":")[1]) is a scheme other than mysql or postgresql, with allowUnknown=false. Malformed URIs without a second colon-separated token can also produce a confusing scheme value here.

Common situations: Metadata storage configured for h2 or another DB while utility code assumes mysql/postgres, typo'd JDBC URIs (jdbc:postgres: instead of jdbc:postgresql:), or custom storage extensions the parser doesn't support.

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

• Path must start with '/'
• Invalid URL format for PostgreSQL: [%s]
• 08001
• connectURI cannot be null or empty
• Path must start with '/'

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