{"record":{"id":"41becd744868f9fb","repo":"SonarSource/sonarqube","slug":"scanner-directory-not-found-s","errorCode":null,"errorMessage":"Scanner directory not found: %s","messagePattern":"Scanner directory not found: (.+?)","errorType":"http","errorClass":"NotFoundException","httpStatus":404,"severity":"error","filePath":"server/sonar-webserver-webapi-v2/src/main/java/org/sonar/server/v2/api/analysis/service/ScannerEngineHandlerImpl.java","lineNumber":49,"sourceCode":"import static org.apache.commons.io.FileUtils.listFiles;\nimport static org.apache.commons.io.filefilter.FileFilterUtils.directoryFileFilter;\nimport static org.apache.commons.io.filefilter.HiddenFileFilter.VISIBLE;\n\npublic class ScannerEngineHandlerImpl implements ScannerEngineHandler {\n\n  private final ServerFileSystem fs;\n\n  private ScannerEngineMetadata scannerEngineMetadata;\n\n  public ScannerEngineHandlerImpl(ServerFileSystem fs) {\n    this.fs = fs;\n  }\n\n  @Override\n  public File getScannerEngine() {\n    File scannerDir = new File(fs.getHomeDir(), \"lib/scanner\");\n    if (!scannerDir.exists()) {\n      throw new NotFoundException(format(\"Scanner directory not found: %s\", scannerDir.getAbsolutePath()));\n    }\n    return listFiles(scannerDir, VISIBLE, directoryFileFilter())\n      .stream()\n      .filter(file -> file.getName().endsWith(\".jar\"))\n      .findFirst()\n      .orElseThrow(() -> new NotFoundException(format(\"Scanner JAR not found in directory: %s\", scannerDir.getAbsolutePath())));\n  }\n\n  private static String getSha256(File file) {\n    try (FileInputStream fileInputStream = new FileInputStream(file)) {\n      return sha256Hex(fileInputStream);\n    } catch (IOException exception) {\n      throw new UncheckedIOException(new IOException(\"Unable to compute SHA-256 checksum of the Scanner Engine\", exception));\n    }\n  }\n\n  @Override\n  public ScannerEngineMetadata getScannerEngineMetadata() {","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/SonarSource/sonarqube/blob/184c821202192afc1c599fc912d0889b69fffa53/server/sonar-webserver-webapi-v2/src/main/java/org/sonar/server/v2/api/analysis/service/ScannerEngineHandlerImpl.java#L31-L67","documentation":"Thrown by ScannerEngineHandlerImpl.getScannerEngine() when the <homeDir>/lib/scanner directory does not exist, meaning the server distribution is incomplete or was not fully deployed. Callers (the scanner engine download endpoint) surface this as a 404.","triggerScenarios":"GET api/v2/analysis/engine when the installation directory lacks lib/scanner; upgrading/partially copying a distribution; deleting lib/scanner manually.","commonSituations":"Manual SonarQube deployments where only some files were copied, container images built with a slimmed/incorrect set of files, hardened setups that stripped lib/scanner, wrong SONAR_HOME pointing at an empty directory.","solutions":["Restore lib/scanner from a complete SonarQube distribution download","Verify the process is using the correct home directory (fs.getHomeDir) pointing to the full installation","Reinstall SonarQube properly instead of copying over an existing installation","Check that deployment/backup tooling does not exclude lib/scanner"],"exampleFix":"// before\nFile scannerDir = new File(fs.getHomeDir(), \"lib/scanner\");\n// after\nFile scannerDir = new File(fs.getHomeDir(), \"lib/scanner\");\nif (!scannerDir.exists()) {\n  // reinstall distribution or restore from the official zip so lib/scanner exists\n  throw new NotFoundException(format(\"Scanner directory not found: %s\", scannerDir.getAbsolutePath()));\n}","handlingStrategy":"try-catch","validationCode":"#!/bin/bash\n# preflight: verify the scanner lib directory exists\nif [ ! -d \"$SONAR_HOME/lib/scanner\" ]; then\n  echo \"lib/scanner missing - reinstall the SonarQube distribution\" >&2\n  exit 1\nfi","typeGuard":"function isDistributionComplete(sonarHome) {\n  return fs.existsSync(path.join(sonarHome, 'lib', 'scanner'));\n}","tryCatchPattern":"try {\n  const engine = await downloadScannerEngine();\n} catch (err) {\n  if (err.status === 404 && /Scanner directory not found/.test(err.message)) {\n    // restore lib/scanner from the official distribution before retrying\n  } else { throw err; }\n}","preventionTips":["Deploy SonarQube from complete official artifacts only","Check that deployment/backup tooling doesn't exclude lib/scanner","Validate the distribution directory after each upgrade","Point the process at the real installation home directory"],"tags":["sonarqube","directory-not-found","scanner-engine"],"backgroundTag":"directory-not-found","analyzedSha":"184c821202192afc1c599fc912d0889b69fffa53","analyzedAt":"2026-09-09T12:23:51.573Z","contentChangedAt":"2026-09-09T12:23:51.573Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}