{"record":{"id":"cb65e643435f2f3d","repo":"pentaho/pentaho-kettle","slug":"cannot-fetch-driver-metadata-for-driverid-jdbc-driver","errorCode":null,"errorMessage":"Cannot fetch driver metadata for '{driverId}': JDBC_DRIVER_SERVICE_URL is not configured. Set the environment variable or system property 'JDBC_DRIVER_SERVICE_URL'.","messagePattern":"Cannot fetch driver metadata for '(.+?)': JDBC_DRIVER_SERVICE_URL is not configured\\. Set the environment variable or system property 'JDBC_DRIVER_SERVICE_URL'\\.","errorType":"exception","errorClass":"KettleDatabaseException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/org/pentaho/di/core/database/Database.java","lineNumber":732,"sourceCode":"  }\n\n  private String appendMssqlInstanceIfNeeded( String url ) {\n    if ( databaseMeta.getDatabaseInterface() instanceof MSSQLServerNativeDatabaseMeta ) {\n      // Handle MSSQL Instance name. Would rather this was handled in the dialect\n      // but cannot (without refactor) get to variablespace for variable substitution from\n      // a BaseDatabaseMeta subclass.\n      String instance = environmentSubstitute( databaseMeta.getSQLServerInstance() );\n      if ( !Utils.isEmpty( instance ) ) {\n        return url + \";instanceName=\" + instance;\n      }\n    }\n    return url;\n  }\n\n  private static Map<String, Object> getMetadataFromDriver( String driverId ) throws KettleDatabaseException {\n    String serviceBaseUrl = Const.getJdbcDriverServiceUrl();\n    if ( serviceBaseUrl == null || serviceBaseUrl.trim().isEmpty() ) {\n      throw new KettleDatabaseException(\n        \"Cannot fetch driver metadata for '\" + driverId + \"': JDBC_DRIVER_SERVICE_URL is not configured. \"\n          + \"Set the environment variable or system property 'JDBC_DRIVER_SERVICE_URL'.\" );\n    }\n\n    String metadataUrl = serviceBaseUrl + \"/api/v1/connection-drivers/\" + driverId;\n    HttpURLConnection conn = null;\n    try {\n      conn = (HttpURLConnection) new URL( metadataUrl ).openConnection();\n      conn.setConnectTimeout( 10_000 );\n      conn.setReadTimeout( 60_000 );\n      conn.setRequestMethod( \"GET\" );\n\n      String bearerToken = CmsTokenProvider.getInstance().getToken();\n      if ( bearerToken != null ) {\n        conn.setRequestProperty( \"Authorization\", \"Bearer \" + bearerToken );\n      }\n\n      int status = conn.getResponseCode();","sourceCodeStart":714,"sourceCodeEnd":750,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/core/src/main/java/org/pentaho/di/core/database/Database.java#L714-L750","documentation":"getMetadataFromDriver requires a base URL for the remote driver-metadata service, read via Const.getJdbcDriverServiceUrl() (env var or system property JDBC_DRIVER_SERVICE_URL). When it is unset or blank the method fails fast with this error before making any HTTP call. It is a configuration precondition, not a network failure.","triggerScenarios":"Calling driverMetadata (e.g. when resolving a dynamic driver's metadata) while JDBC_DRIVER_SERVICE_URL is neither set as an environment variable nor as a -D system property, or is set to whitespace only.","commonSituations":"Fresh install/CI container where the service URL was never provisioned; renaming the env var in deployment configs; running Pentaho locally without the metadata service config; YAML/k8s manifest missing the env entry.","solutions":["Set the environment variable JDBC_DRIVER_SERVICE_URL to the metadata service base URL (e.g. http://metadata-service:8080)","Or pass the Java system property -DJDBC_DRIVER_SERVICE_URL=http://metadata-service:8080 on startup","Verify the value is non-blank at startup (fail fast in launcher scripts)","If metadata is optional for your deployment, ensure the calling code path handles/disables driver metadata lookup"],"exampleFix":"// before\npdi.sh  # JDBC_DRIVER_SERVICE_URL unset\n// after\nexport JDBC_DRIVER_SERVICE_URL=http://driver-metadata:8080\n./pdi.sh","handlingStrategy":"validation","validationCode":"String url = System.getenv(\"JDBC_DRIVER_SERVICE_URL\");\nif (url == null) url = System.getProperty(\"JDBC_DRIVER_SERVICE_URL\");\nif (url == null || url.trim().isEmpty()) throw new IllegalStateException(\"JDBC_DRIVER_SERVICE_URL must be set before connecting\");","typeGuard":"boolean hasDriverServiceUrl() { String u = Const.getJdbcDriverServiceUrl(); return u != null && !u.trim().isEmpty(); }","tryCatchPattern":"try { map = db.driverMetadata(driverId); } catch (KettleDatabaseException e) { if (e.getMessage().contains(\"JDBC_DRIVER_SERVICE_URL is not configured\")) { log.error(\"Set JDBC_DRIVER_SERVICE_URL env/system property\"); } else throw e; }","preventionTips":["Set JDBC_DRIVER_SERVICE_URL in every deployment manifest (Docker/k8s/systemd)","Fail fast at application startup if the property is missing","Document the requirement in setup/README","Validate the value is a well-formed URL at startup"],"tags":["configuration","environment-variable","jdbc","metadata"],"backgroundTag":"missing-env-var","analyzedSha":"f3058517a153da500bf4551f46d79b91bf8ec552","analyzedAt":"2026-09-13T14:04:16.340Z","contentChangedAt":"2026-09-13T14:04:16.340Z","schemaVersion":2},"datasetVersion":"2026-09-20T23:17:15.980Z"}