SonarSource/sonarqube · error · IllegalStateException

Unknown type of SMTP secure connection:

Error message

Unknown type of SMTP secure connection: 

What it means

EmailSender.configureSecureConnection supports exactly three `sonar.email.smtp.secureConnection` values: SSL, STARTTLS, and NONE. Any other value throws an IllegalStateException when an email notification is being sent, since commons-email's email object cannot be safely configured without a known security mode.

Solutions

1. Set secureConnection to exactly `SSL`, `STARTTLS`, or `NONE` (uppercase, no whitespace).
2. Use `STARTTLS` for TLS-upgrade SMTP (typically port 587), `SSL` for implicit TLS (port 465).
3. Leave empty or set `NONE` for unauthenticated local relays.
4. Re-test by triggering a test notification after saving settings.

Example fix

// before (sonar.properties)
sonar.email.smtp.secureConnection=tls
// after
sonar.email.smtp.secureConnection=STARTTLS

String sc = settings.optString("sonar.email.smtp.secureConnection", "NONE").trim().toUpperCase(Locale.ROOT);
if (!Set.of("SSL", "STARTTLS", "NONE").contains(sc)) {
  throw new IllegalArgumentException("secureConnection must be SSL, STARTTLS or NONE: " + sc);
}

When it happens

Trigger: Setting sonar.email.smtp.secureConnection in sonar.properties or the Administration > Email settings to a value other than SSL/STARTTLS/NONE (e.g. `ssl` lowercase handled elsewhere, `tls`, `none ` with whitespace), then triggering an email.

Common situations: Documentation confusion between `STARTTLS` and `TLS`; values copied from other mail clients (`ssl/tls`); trailing spaces or wrong case in the settings UI.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Email configuration doesn't exist.
• Email configuration with id
• Unknown type of SMTP secure connection:
• Fail to decrypt the property
• Failed to send quality gate change email notification for…

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

Appendix: source

Thrown at server/sonar-server-common/src/main/java/org/sonar/server/email/EmailSender.java:131

  private void configureSecureConnection(MultiPartEmail email) {
    if (CI.equals(emailSmtpConfiguration.getSecureConnection(), "SSLTLS")) {
      email.setSSLOnConnect(true);
      email.setSSLCheckServerIdentity(true);
      email.setSslSmtpPort(String.valueOf(emailSmtpConfiguration.getSmtpPort()));

      // this port is not used except in EmailException message, that's why it's set with the same value than SSL port.
      // It prevents from getting bad message.
      email.setSmtpPort(emailSmtpConfiguration.getSmtpPort());
    } else if (CI.equals(emailSmtpConfiguration.getSecureConnection(), "STARTTLS")) {
      email.setStartTLSEnabled(true);
      email.setStartTLSRequired(true);
      email.setSSLCheckServerIdentity(true);
      email.setSmtpPort(emailSmtpConfiguration.getSmtpPort());
    } else if (CI.equals(emailSmtpConfiguration.getSecureConnection(), "NONE")) {
      email.setSmtpPort(emailSmtpConfiguration.getSmtpPort());
    } else {
      throw new IllegalStateException("Unknown type of SMTP secure connection: " + emailSmtpConfiguration.getSecureConnection());
    }
  }

}

View on GitHub (pinned to 184c821202)