SonarSource/sonarqube · error · IllegalStateException

"Fail to set multiple values on a single value property " +

Error message

"Fail to set multiple values on a single value property " + key

What it means

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.

Source

Thrown at sonar-plugin-api-impl/src/main/java/org/sonar/api/config/internal/Settings.java:346

  }

  public Settings appendProperty(String key, @Nullable String value) {
    Optional<String> existingValue = getRawString(definitions.validKey(key));
    String newValue;
    if (!existingValue.isPresent()) {
      newValue = trim(value);
    } else {
      newValue = existingValue.get() + "," + trim(value);
    }
    return setProperty(key, newValue);
  }

  public Settings setProperty(String key, @Nullable String[] values) {
    requireNonNull(key, "key can't be null");
    String effectiveKey = key.trim();
    Optional<PropertyDefinition> def = getDefinition(effectiveKey);
    if (!def.isPresent() || (!def.get().multiValues())) {
      throw new IllegalStateException("Fail to set multiple values on a single value property " + key);
    }

    String text = null;
    if (values != null) {
      List<String> escaped = new ArrayList<>();
      for (String value : values) {
        if (null != value) {
          escaped.add(value.replace(",", "%2C"));
        } else {
          escaped.add("");
        }
      }

      String escapedValue = escaped.stream().collect(Collectors.joining(","));
      text = trim(escapedValue);
    }
    return setProperty(key, text);
  }

View on GitHub (pinned to 184c821202)

Solutions

  1. Declare the property definition with multiValues=true in the plugin's PropertyDefinitions
  2. Join the values yourself and call setProperty(String) if single-valued is intended
  3. Verify the property key spelling and that the defining plugin is loaded/registered
  4. Remove the extra values and set a single value when the setting only accepts one

Example fix

// before
settings.setProperty("sonar.exclusions", new String[]{"**/*.gen.java"}); // definition missing/single-valued
// after
PropertyDefinition.builder("sonar.exclusions").multiValues(true).build(); // register this definition
Defensive patterns

Strategy: validation

Validate before calling

// check the property accepts multiple values before setting an array
Optional<PropertyDefinition> def = definitions.get(key);
if (def.isEmpty()) {
  throw new IllegalArgumentException("unknown property: " + key);
}
if (!def.get().multiValues()) {
  // set a single joined/first value instead of an array
  return settings.setProperty(key, values == null ? null : String.join(",", values));
}

Try / catch

try {
  return settings.setProperty(key, values);
} catch (IllegalStateException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Fail to set multiple values")) {
    log.error("Property {} is single-valued; pass a single String instead", key);
  }
  throw e;
}

Prevention

When it happens

Trigger: 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[].

Common situations: 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.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of SonarSource/sonarqube@184c821202 (2026-09-09). Data as JSON: /api/errors/0689c09d10ba4270. Report an issue: GitHub.