SonarSource/sonarqube · error · IllegalArgumentException

The description is missing

Error message

The description is missing

What it means

RuleUpdater.updateDescription requires a non-null, non-empty markdown description; when update.getMarkdownDescription() is null or empty the update fails with IllegalArgumentException('The description is missing'). A rule update that resets the description must always supply usable Markdown content.

Solutions

  1. Provide non-empty 'markdown_description' text in the api/rules/update request
  2. Validate the description is non-blank client-side before submitting
  3. If only other fields should change, do not include an empty description parameter in the payload

Example fix

// before
POST api/rules/update?key=custom:S123&name=MyRule&markdown_description=
// after
POST api/rules/update?key=custom:S123&name=MyRule&markdown_description=This+rule+flags+...
Defensive patterns

Strategy: validation

Validate before calling

if (!description || !description.trim()) throw new Error("api/rules/update requires a non-empty 'markdown_description'");

Type guard

function hasDescription(p) {
  return typeof p.markdown_description === 'string' && p.markdown_description.trim().length > 0;
}

Try / catch

try {
  await post("api/rules/update", params);
} catch (e) {
  if (String(e.message).includes("The description is missing")) {
    console.error("Provide markdown_description text; empty descriptions are rejected");
  }
}

Prevention

When it happens

Trigger: Calling api/rules/update with 'markdown_description' omitted or empty while the update flow routes through updateDescription (e.g. updating a custom rule's description section).

Common situations: Migrating custom rules whose description field was never set; scripts sending empty description strings to 'clear' the description; form submissions where the description textarea was left blank.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at server/sonar-webserver-webapi/src/main/java/org/sonar/server/rule/RuleUpdater.java:172

        i.setSeverity(value);
        if (RuleTypeMapper.toRuleType(convertToRuleType(key)) == RuleType.fromDbConstant(rule.getType())) {
          rule.setSeverity(convertToDeprecatedSeverity(value));
        }
      }));
  }

  private static void updateName(RuleUpdate update, RuleDto rule) {
    String name = update.getName();
    if (isNullOrEmpty(name)) {
      throw new IllegalArgumentException("The name is missing");
    }
    rule.setName(name);
  }

  private void updateDescription(RuleUpdate update, RuleDto rule) {
    String description = update.getMarkdownDescription();
    if (isNullOrEmpty(description)) {
      throw new IllegalArgumentException("The description is missing");
    }
    RuleDescriptionSectionDto descriptionSectionDto = createDefaultRuleDescriptionSection(uuidFactory.create(), description);
    rule.setDescriptionFormat(RuleDto.Format.MARKDOWN);
    rule.replaceRuleDescriptionSectionDtos(List.of(descriptionSectionDto));
  }

  private static void updateSeverity(RuleUpdate update, RuleDto rule) {
    String severity = update.getSeverity();
    if (isNullOrEmpty(severity) || !Severity.ALL.contains(severity)) {
      throw new IllegalArgumentException("The severity is invalid");
    }
    rule.setSeverity(severity);
    updateImpactSeverity(rule, severity);
  }

  private static void updateStatus(RuleUpdate update, RuleDto rule) {
    RuleStatus status = update.getStatus();
    if (status == null) {

View on GitHub (pinned to 184c821202)