pentaho/pentaho-kettle · error · KettleDatabaseException

JdbcDriverResolver: Cannot convert path to URL: " +…

Error message

JdbcDriverResolver: Cannot convert path to URL: " + jarAbsolutePath

What it means

Final guard in toJarUrl(): if File.toPath().toUri().toURL() throws (MalformedURLException or an invalid path/URI conversion, e.g. illegal characters or a path not expressible as a URI), the exception is wrapped in this KettleDatabaseException.

Solutions

1. Remove illegal characters (spaces, '#', '%', non-ASCII) from the drivers directory path
2. Use a simple ASCII path without spaces for JDBC_DRIVERS_DIRECTORY
3. Read the cause for the exact MalformedURLException reason

Example fix

// before
JDBC_DRIVERS_DIRECTORY=/opt/My Drivers/jdbc  # space breaks toURL()
// after
JDBC_DRIVERS_DIRECTORY=/opt/my-drivers/jdbc

try { new File( path ).toPath().toUri().toURL(); } catch ( Exception e ) { throw new IllegalStateException( "path not URL-convertible: " + path, e ); }

try { toJarUrl( path ); } catch ( KettleDatabaseException e ) { if ( e.getMessage().contains( "Cannot convert path to URL" ) ) sanitizePathAndRetry( path ); throw e; }

When it happens

Trigger: jarAbsolutePath contains characters illegal in a URI/URL (spaces unencoded, non-ASCII or control characters, platform-specific oddities on Windows), causing toURL() to fail even though the file exists.

Common situations: Drivers directory path containing spaces or special characters; paths copied with trailing characters; Windows paths with unusual drive mappings inside containers.

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

• Dynamic driver ' ' does not accept URL: — check the JDBC…
• Dynamic driver ' ' returned null for URL: — check that the…
• Dynamic driver ' ' threw exception checking URL
• Unable to assemble URL from database
• Unable to construct a JDBC URL: at least the database name…

AI-assisted analysis of pentaho/pentaho-kettle@f3058517a1 (2026-09-13). Data as JSON: /api/errors/f291106480d4d468. Report an issue: GitHub.

Appendix: source

Thrown at core/src/main/java/org/pentaho/di/core/database/JdbcDriverResolver.java:407

   * and has a {@code .jar} extension.
   *
   * @param jarAbsolutePath absolute path to the JAR file
   * @return the file URL
   * @throws KettleDatabaseException if the file does not exist, is not a regular file,
   *                                  does not end with .jar, or cannot be converted
   */
  private static URL toJarUrl( String jarAbsolutePath ) throws KettleDatabaseException {
    File jarFile = new File( jarAbsolutePath );
    if ( !jarFile.exists() || !jarFile.isFile() ) {
      throw new KettleDatabaseException( "JdbcDriverResolver: JAR not found: " + jarAbsolutePath );
    }
    if ( !jarFile.getName().toLowerCase().endsWith( ".jar" ) ) {
      throw new KettleDatabaseException( "JdbcDriverResolver: not a JAR file: " + jarAbsolutePath );
    }
    try {
      return jarFile.toPath().toUri().toURL();
    } catch ( Exception e ) {
      throw new KettleDatabaseException( "JdbcDriverResolver: Cannot convert path to URL: " + jarAbsolutePath, e );
    }
  }
}

View on GitHub (pinned to f3058517a1)