{"record":{"id":"56a0087c88197d09","repo":"SonarSource/sonarqube","slug":"fail-to-decrypt-the-property-effectivekey","errorCode":null,"errorMessage":"\"Fail to decrypt the property \" + effectiveKey + \". Please check your secret key.\"","messagePattern":"\"Fail to decrypt the property \" \\+ effectiveKey \\+ \"\\. Please check your secret key\\.\"","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"sonar-plugin-api-impl/src/main/java/org/sonar/api/config/internal/Settings.java","lineNumber":150,"sourceCode":"   * then the returned value is decrypted.\n   * </p>\n   *\n   * @throws IllegalStateException if value is encrypted but fails to be decrypted.\n   */\n  @CheckForNull\n  @Override\n  public String getString(String key) {\n    String effectiveKey = definitions.validKey(key);\n    Optional<String> value = getRawString(effectiveKey);\n    if (!value.isPresent()) {\n      // default values cannot be encrypted, so return value as-is.\n      return getDefaultValue(effectiveKey);\n    }\n    if (encryption.isEncrypted(value.get())) {\n      try {\n        return encryption.decrypt(value.get());\n      } catch (Exception e) {\n        throw new IllegalStateException(\"Fail to decrypt the property \" + effectiveKey + \". Please check your secret key.\", e);\n      }\n    }\n    return value.get();\n  }\n\n  /**\n   * Effective value as boolean. It is {@code false} if {@link #getString(String)}\n   * does not return {@code \"true\"}, even if it's not a boolean representation.\n   *\n   * @return {@code true} if the effective value is {@code \"true\"}, else {@code false}.\n   */\n  @Override\n  public boolean getBoolean(String key) {\n    String value = getString(key);\n    return StringUtils.isNotEmpty(value) && Boolean.parseBoolean(value);\n  }\n\n  /**","sourceCodeStart":132,"sourceCodeEnd":168,"githubUrl":"https://github.com/SonarSource/sonarqube/blob/184c821202192afc1c599fc912d0889b69fffa53/sonar-plugin-api-impl/src/main/java/org/sonar/api/config/internal/Settings.java#L132-L168","documentation":"Settings.getString reads a setting and, if the stored value is encrypted (marked by the encryption prefix), decrypts it with the configured secret key via the Encryption/AesECBCipher. Any exception during decryption is wrapped in this IllegalStateException naming the property. The library throws it because returning an undecryptable value would silently corrupt configuration.","triggerScenarios":"Calling getString(key) (directly or via getInt/getBoolean/etc.) on a property whose value is encrypted but whose sonar-secret.txt is missing, unreadable, or different from the key used when encrypting.","commonSituations":"Migrating a SonarQube database to a new instance without copying sonar-secret.txt; regenerating the secret key; running web/CE nodes with different or absent secret keys; permission problems reading ~/.sonar/sonar-secret.txt.","solutions":["Copy the original sonar-secret.txt (default ~/.sonar/sonar-secret.txt or sonar.pathToSecretKey location) to the node reading the property","Re-encrypt the property with the current secret key so it matches the installed key","Verify file read permissions on the secret key file for the SonarQube process user","Re-enter the value in clear text and re-save it via the UI/API to re-encrypt with the current key"],"exampleFix":"// before\nString pwd = settings.getString(\"sonar.jdbc.password\"); // encrypted value, wrong key\n// after\n// install matching sonar-secret.txt first, then\nString pwd = settings.getString(\"sonar.jdbc.password\");","handlingStrategy":"try-catch","validationCode":"// verify secret key file exists and is readable before reading encrypted settings\njava.io.File secret = new java.io.File(\n    System.getProperty(\"user.home\"), \".sonar/sonar-secret.txt\");\nif (!secret.canRead()) {\n  throw new IllegalStateException(\"secret key file missing/unreadable: \" + secret);\n}","typeGuard":null,"tryCatchPattern":"try {\n  return settings.getString(key);\n} catch (IllegalStateException e) {\n  if (e.getMessage() != null && e.getMessage().startsWith(\"Fail to decrypt the property\")) {\n    log.error(\"Install the original sonar-secret.txt or re-encrypt property {}\", key);\n  }\n  throw e;\n}","preventionTips":["Copy sonar-secret.txt whenever migrating or cloning SonarQube instances","Rotate keys only after re-encrypting all encrypted settings","Grant the service user read access to the secret key file","Keep secret key paths consistent across web/CE/ES nodes"],"tags":["crypto","decryption","configuration","secret-key"],"backgroundTag":"missing-credentials","analyzedSha":"184c821202192afc1c599fc912d0889b69fffa53","analyzedAt":"2026-09-09T12:23:51.573Z","contentChangedAt":"2026-09-09T12:23:51.573Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}