{"record":{"id":"d99f18f7e60550ff","repo":"SonarSource/sonarqube","slug":"fail-to-create-or-clean-up-directory-s","errorCode":null,"errorMessage":"Fail to create or clean-up directory %s","messagePattern":"Fail to create or clean-up directory (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"server/sonar-webserver/src/main/java/org/sonar/server/app/TomcatContexts.java","lineNumber":94,"sourceCode":"  }\n\n  static String getContextPath(Props props) {\n    String context = props.value(WEB_CONTEXT.getKey(), \"\");\n    if (\"/\".equals(context)) {\n      context = \"\";\n    } else if (!\"\".equals(context) && context != null && !context.startsWith(\"/\")) {\n      throw MessageException.of(format(\"Value of '%s' must start with a forward slash: '%s'\", WEB_CONTEXT.getKey(), context));\n    }\n    return context;\n  }\n\n  @VisibleForTesting\n  StandardContext addStaticDir(Tomcat tomcat, String contextPath, File dir) {\n    try {\n      fs.createOrCleanupDir(dir);\n      configureDeployErrorPages(dir, contextPath);\n    } catch (IOException e) {\n      throw new IllegalStateException(format(\"Fail to create or clean-up directory %s\", dir.getAbsolutePath()), e);\n    }\n\n    return addContext(tomcat, contextPath, dir);\n  }\n\n  private static StandardContext addContext(Tomcat tomcat, String contextPath, File dir) {\n    try {\n      StandardContext context = (StandardContext) tomcat.addWebapp(contextPath, dir.getAbsolutePath());\n      context.setClearReferencesHttpClientKeepAliveThread(false);\n      context.setClearReferencesStopThreads(false);\n      context.setClearReferencesStopTimerThreads(false);\n      context.setClearReferencesStopTimerThreads(false);\n      context.setAntiResourceLocking(false);\n      context.setReloadable(false);\n      context.setUseHttpOnly(true);\n      context.setTldValidation(false);\n      context.setXmlValidation(false);\n      context.setXmlNamespaceAware(false);","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/SonarSource/sonarqube/blob/184c821202192afc1c599fc912d0889b69fffa53/server/sonar-webserver/src/main/java/org/sonar/server/app/TomcatContexts.java#L76-L112","documentation":"TomcatContexts.addStaticDir serves SonarQube's static content from a filesystem directory. It first calls Fs.createOrCleanupDir (forcing directory creation/cleanup via FileUtils.forceMkdir); if that raises IOException, the directory could not be created or cleaned and an IllegalStateException wrapping it is thrown, failing server startup.","triggerScenarios":"The static-content directory (e.g. $SONARQUBE_HOME/web) cannot be created because of insufficient filesystem permissions, a read-only volume, or because a non-directory FILE already exists at that path (cleanup fails).","commonSituations":"Running the SonarQube process as a user without write access to the installation directory; installing over an existing 'web' file; read-only Docker layer or mounted volume; disk full.","solutions":["Check permissions on the directory's parent and ensure the sonar process user can write there; chown/chmod as needed","Delete any plain FILE named like the expected directory so it can be created as a directory","Ensure the volume is writable and has free space (Docker: use a writable volume, not a read-only mount)"],"exampleFix":"// before\nsudo -u otheruser ./sonar.sh start  # user can't write to install dir\n// after\nsudo chown -R sonar:sonar /opt/sonarqube && sudo -u sonar ./sonar.sh start","handlingStrategy":"validation","validationCode":"File dir = new File(home, \"web\");\nif (dir.exists() && !dir.isDirectory()) throw new IllegalStateException(dir + \" exists and is not a directory\");\nif (!dir.exists() && !dir.getParentFile().canWrite()) throw new IllegalStateException(\"No write permission on \" + dir.getParentFile());","typeGuard":null,"tryCatchPattern":"try { server.start(); } catch (IllegalStateException e) { if (e.getMessage().contains(\"Fail to create or clean-up directory\")) { log.error(\"Check permissions/ownership of the SonarQube install dir for the process user\"); } throw e; }","preventionTips":["Run SonarQube as a user owning its installation directory (chown -R)","Avoid installing into read-only volumes or Docker read-only mounts","Do not place plain files where directories (e.g. 'web') are expected"],"tags":["filesystem","directory","startup"],"backgroundTag":"mkdir-permission-denied","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"}