{"record":{"id":"24db924351fd3b79","repo":"SonarSource/sonarqube","slug":"directory-must-contain-only-one-jar-file","errorCode":null,"errorMessage":"Directory must contain only one JAR file: ","messagePattern":"Directory must contain only one JAR file: ","errorType":"validation","errorClass":"MessageException","httpStatus":null,"severity":"error","filePath":"server/sonar-main/src/main/java/org/sonar/application/config/JdbcSettings.java","lineNumber":91,"sourceCode":"\n  private static List<String> additionalMsSqlLibPaths(File homeDir) {\n    File dir = new File(homeDir, Provider.SQLSERVER.path);\n    List<File> files = new ArrayList<>(FileUtils.listFiles(dir, new String[] {\"jar\"}, false));\n    return files.stream().filter(f -> !f.getName().startsWith(\"mssql-jdbc\")).map(File::getAbsolutePath).toList();\n  }\n\n  String driverPath(File homeDir, Provider provider) {\n    String dirPath = provider.path;\n    File dir = new File(homeDir, dirPath);\n    if (!dir.exists()) {\n      throw new MessageException(\"Directory does not exist: \" + dirPath);\n    }\n    List<File> files = new ArrayList<>(FileUtils.listFiles(dir, new String[] {\"jar\"}, false));\n    if (files.isEmpty()) {\n      throw new MessageException(\"Directory does not contain JDBC driver: \" + dirPath);\n    }\n    if (files.size() > 1 && Provider.SQLSERVER != provider) {\n      throw new MessageException(\"Directory must contain only one JAR file: \" + dirPath);\n    } else if (Provider.SQLSERVER == provider) {\n      return files.stream().filter(f -> f.getName().startsWith(\"mssql-jdbc\")).findFirst()\n        .orElseThrow(() -> new MessageException(\"Directory does not contain JDBC driver: \" + dirPath)).getAbsolutePath();\n    }\n    return files.get(0).getAbsolutePath();\n  }\n\n  Provider resolveProviderAndEnforceNonnullJdbcUrl(Props props) {\n    String url = props.value(JDBC_URL.getKey());\n    Integer embeddedDatabasePort = props.valueAsInt(JDBC_EMBEDDED_PORT.getKey());\n\n    if (embeddedDatabasePort != null) {\n      String correctUrl = buildH2JdbcUrl(embeddedDatabasePort);\n      warnIfUrlIsSet(embeddedDatabasePort, url, correctUrl);\n      props.set(JDBC_URL.getKey(), correctUrl);\n      return Provider.H2;\n    }\n","sourceCodeStart":73,"sourceCodeEnd":109,"githubUrl":"https://github.com/SonarSource/sonarqube/blob/184c821202192afc1c599fc912d0889b69fffa53/server/sonar-main/src/main/java/org/sonar/application/config/JdbcSettings.java#L73-L109","documentation":"For all providers except SQLSERVER, the driver directory must contain exactly one JAR file. If more than one .jar is present, driverPath throws MessageException 'Directory must contain only one JAR file: <path>' because it cannot decide which driver to load.","triggerScenarios":"Dropping multiple JDBC JARs (e.g. an old and a new driver version) into the same driver directory for a non-SQLSERVER provider.","commonSituations":"Upgrading a driver by copying the new JAR alongside the old one; bundling driver plus helper JARs (e.g. shardingsphere or pooling libs) into the same folder.","solutions":["Remove all but one JDBC driver JAR from the directory","Keep only the driver version matching your database","Move auxiliary/dependency JARs to a different directory","For multiple JAR needs, switch to the SQLSERVER provider path only if it is actually SQL Server"],"exampleFix":"// before\nls extensions/jdbc-driver/postgres  # postgresql-42.2.5.jar postgresql-42.7.3.jar\n// after\nrm extensions/jdbc-driver/postgres/postgresql-42.2.5.jar  # keep exactly one","handlingStrategy":"validation","validationCode":"File[] jars = dir.listFiles((d, n) -> n.toLowerCase().endsWith(\".jar\"));\nif (jars != null && jars.length > 1) throw new IllegalStateException(\"Multiple driver JARs in \" + dir + \"; keep exactly one\");","typeGuard":"static boolean hasSingleJar(File dir) { File[] f = dir.listFiles((d, n) -> n.endsWith(\".jar\")); return f != null && f.length == 1; }","tryCatchPattern":"try { jdbcSettings.start(); } catch (MessageException e) { if (e.getMessage().startsWith(\"Directory must contain only one JAR\")) { cleanupOldJars(); } throw e; }","preventionTips":["Delete old driver versions when upgrading instead of keeping both","Keep only the JDBC driver in the driver directory (no helper JARs)","Automate upgrades to replace (not append) driver files","Document that only SQLSERVER may select a JAR by name prefix"],"tags":["filesystem","jdbc","driver","configuration"],"backgroundTag":"conflicting-config-options","analyzedSha":"184c821202192afc1c599fc912d0889b69fffa53","analyzedAt":"2026-09-09T12:23:51.573Z","contentChangedAt":"2026-09-09T12:23:51.573Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}