{"record":{"id":"0689c09d10ba4270","repo":"SonarSource/sonarqube","slug":"fail-to-set-multiple-values-on-a-single-value-pro","errorCode":null,"errorMessage":"\"Fail to set multiple values on a single value property \" + key","messagePattern":"\"Fail to set multiple values on a single value property \" \\+ key","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"sonar-plugin-api-impl/src/main/java/org/sonar/api/config/internal/Settings.java","lineNumber":346,"sourceCode":"  }\n\n  public Settings appendProperty(String key, @Nullable String value) {\n    Optional<String> existingValue = getRawString(definitions.validKey(key));\n    String newValue;\n    if (!existingValue.isPresent()) {\n      newValue = trim(value);\n    } else {\n      newValue = existingValue.get() + \",\" + trim(value);\n    }\n    return setProperty(key, newValue);\n  }\n\n  public Settings setProperty(String key, @Nullable String[] values) {\n    requireNonNull(key, \"key can't be null\");\n    String effectiveKey = key.trim();\n    Optional<PropertyDefinition> def = getDefinition(effectiveKey);\n    if (!def.isPresent() || (!def.get().multiValues())) {\n      throw new IllegalStateException(\"Fail to set multiple values on a single value property \" + key);\n    }\n\n    String text = null;\n    if (values != null) {\n      List<String> escaped = new ArrayList<>();\n      for (String value : values) {\n        if (null != value) {\n          escaped.add(value.replace(\",\", \"%2C\"));\n        } else {\n          escaped.add(\"\");\n        }\n      }\n\n      String escapedValue = escaped.stream().collect(Collectors.joining(\",\"));\n      text = trim(escapedValue);\n    }\n    return setProperty(key, text);\n  }","sourceCodeStart":328,"sourceCodeEnd":364,"githubUrl":"https://github.com/SonarSource/sonarqube/blob/184c821202192afc1c599fc912d0889b69fffa53/sonar-plugin-api-impl/src/main/java/org/sonar/api/config/internal/Settings.java#L328-L364","documentation":"Settings.setProperty(key, String[]) sets a multi-valued property as a comma-joined string. The library first checks the property definition; if the key has no PropertyDefinition or is declared single-valued (multiValues() false), setting an array is rejected with this IllegalStateException. It throws because an array of values has no valid representation in a single-value property.","triggerScenarios":"Calling setProperty(key, String[]) where key is not defined by any PropertyDefinition, or where its definition was declared with multiValues=false; also hit via addSettings/addProperties when a map value is a String[].","commonSituations":"Setting array values for core settings that are single-valued; property renamed or removed so the definition lookup fails; plugin not loaded so the multiValues definition is missing; tests constructing Settings without property definitions registered.","solutions":["Declare the property definition with multiValues=true in the plugin's PropertyDefinitions","Join the values yourself and call setProperty(String) if single-valued is intended","Verify the property key spelling and that the defining plugin is loaded/registered","Remove the extra values and set a single value when the setting only accepts one"],"exampleFix":"// before\nsettings.setProperty(\"sonar.exclusions\", new String[]{\"**/*.gen.java\"}); // definition missing/single-valued\n// after\nPropertyDefinition.builder(\"sonar.exclusions\").multiValues(true).build(); // register this definition","handlingStrategy":"validation","validationCode":"// check the property accepts multiple values before setting an array\nOptional<PropertyDefinition> def = definitions.get(key);\nif (def.isEmpty()) {\n  throw new IllegalArgumentException(\"unknown property: \" + key);\n}\nif (!def.get().multiValues()) {\n  // set a single joined/first value instead of an array\n  return settings.setProperty(key, values == null ? null : String.join(\",\", values));\n}","typeGuard":null,"tryCatchPattern":"try {\n  return settings.setProperty(key, values);\n} catch (IllegalStateException e) {\n  if (e.getMessage() != null && e.getMessage().startsWith(\"Fail to set multiple values\")) {\n    log.error(\"Property {} is single-valued; pass a single String instead\", key);\n  }\n  throw e;\n}","preventionTips":["Declare multiValues(true) in the PropertyDefinition for multi-valued settings","Check multiValues() before passing String[]","Confirm the defining plugin is loaded so the definition exists","Use setProperty(String) for single-value settings"],"tags":["configuration","multi-value","property-definition"],"backgroundTag":"invalid-argument-value","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"}