{"record":{"id":"7c97972d1ca4d31d","repo":"SonarSource/sonarqube","slug":"property-s-cannot-be-changed-on-restart-s","errorCode":null,"errorMessage":"Property [%s] cannot be changed on restart: [%s] => [%s]","messagePattern":"Property \\[(.+?)\\] cannot be changed on restart: \\[(.+?)\\] => \\[(.+?)\\]","errorType":"validation","errorClass":"MessageException","httpStatus":null,"severity":"error","filePath":"server/sonar-main/src/main/java/org/sonar/application/AppReloaderImpl.java","lineNumber":77,"sourceCode":"\n    fileSystem.reset();\n    logging.configure();\n    appState.reset();\n  }\n\n  private static void ensureUnchangedConfiguration(Props oldProps, Props newProps) {\n    verifyUnchanged(oldProps, newProps, PATH_DATA.getKey());\n    verifyUnchanged(oldProps, newProps, PATH_WEB.getKey());\n    verifyUnchanged(oldProps, newProps, PATH_LOGS.getKey());\n    verifyUnchanged(oldProps, newProps, PATH_TEMP.getKey());\n    verifyUnchanged(oldProps, newProps, CLUSTER_ENABLED.getKey());\n  }\n\n  private static void verifyUnchanged(Props initialProps, Props newProps, String propKey) {\n    String initialValue = initialProps.nonNullValue(propKey);\n    String newValue = newProps.nonNullValue(propKey);\n    if (!Objects.equals(initialValue, newValue)) {\n      throw new MessageException(format(\"Property [%s] cannot be changed on restart: [%s] => [%s]\", propKey, initialValue, newValue));\n    }\n  }\n\n}\n","sourceCodeStart":59,"sourceCodeEnd":82,"githubUrl":"https://github.com/SonarSource/sonarqube/blob/184c821202192afc1c599fc912d0889b69fffa53/server/sonar-main/src/main/java/org/sonar/application/AppReloaderImpl.java#L59-L82","documentation":"On reload/restart, AppReloaderImpl.ensureUnchangedConfiguration compares old vs newly loaded props for keys that must not change (process/ports/paths). verifyUnchanged throws this MessageException naming the property and its old => new values whenever any such key differs, aborting the restart so the operator restarts the JVM fully instead.","triggerScenarios":"Editing conf/sonar.properties (or env vars feeding it) to change a protected key — e.g. sonar.web.port, sonar.ce.port, sonar.search.port, sonar.path.* — and then triggering an in-place restart (api/system/restart).","commonSituations":"Admins changing port or path settings and expecting the in-app Restart button to apply them; configuration management tools rewriting sonar.properties between server start and restart request.","solutions":["Perform a full process restart (systemctl restart sonarqube / restart the JVM) so the new value takes effect.","Revert the protected property to its original value if an in-place restart is required.","Only change unprotected settings if you intend to use the in-app restart.","Coordinate config-management runs with full restarts rather than in-app restarts."],"exampleFix":"// before\n$ edit sonar.properties (sonar.web.port=9001)\n$ curl -X POST .../api/system/restart  // MessageException\n// after\n$ sudo systemctl restart sonarqube  // full restart applies the change","handlingStrategy":"validation","validationCode":"Set<String> locked = Set.of(\"sonar.web.port\", \"sonar.ce.port\", \"sonar.search.port\", \"sonar.path.data\", \"sonar.path.temp\");\nProps fresh = settingsLoader.load().getProps();\nfor (String key : locked) {\n    if (!Objects.equals(initialProps.nonNullValue(key), fresh.nonNullValue(key))) {\n        throw new IllegalStateException(key + \" changed; full restart required\");\n    }\n}","typeGuard":null,"tryCatchPattern":"try { reloader.reload(settings); } catch (MessageException e) { log.warning(e.getMessage() + \" -> perform a full process restart\"); }","preventionTips":["Treat port and path properties as restart-only; never expect in-app restart to apply them.","Diff sonar.properties before requesting an in-app restart.","Schedule full service restarts when protected settings change via config management."],"tags":["configuration","restart","immutable-property"],"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"}