SonarSource/sonarqube · error · LdapException

The property '%s' property is empty while it is mandatory.

Error message

The property '%s' property is empty while it is mandatory.

What it means

initLdapContextFactory requires the '<prefix>.url' property to be present and non-blank; otherwise it throws this LdapException using the MANDATORY_LDAP_PROPERTY_ERROR template. The LDAP connection factory cannot be built without a directory URL, so this fails fast during settings initialization.

Source

Thrown at server/sonar-auth-ldap/src/main/java/org/sonar/auth/ldap/LdapSettingsManager.java:186

    contextFactories.put(DEFAULT_LDAP_SERVER_KEY, contextFactory);
  }

  private void initMultiLdapConfiguration(String[] serverKeys) {
    if (config.hasKey("ldap.url") || config.hasKey("ldap.realm")) {
      throw new LdapException("When defining multiple LDAP servers with the property '" + LDAP_SERVERS_PROPERTY + "', "
        + "all LDAP properties must be linked to one of those servers. Please remove properties like 'ldap.url', 'ldap.realm', ...");
    }
    for (String serverKey : serverKeys) {
      LdapContextFactory contextFactory = initLdapContextFactory(LDAP_PROPERTY_PREFIX + "." + serverKey);
      contextFactories.put(serverKey, contextFactory);
    }
  }

  private LdapContextFactory initLdapContextFactory(String prefix) {
    String ldapUrlKey = prefix + ".url";
    String ldapUrl = config.get(ldapUrlKey).orElse(null);
    if (StringUtils.isBlank(ldapUrl)) {
      throw new LdapException(String.format(MANDATORY_LDAP_PROPERTY_ERROR, ldapUrlKey));
    }
    return new LdapContextFactory(config, prefix, ldapUrl);
  }

}

View on GitHub (pinned to 184c821202)

Solutions

  1. Set sonar.authenticator.ldap.url (e.g. ldap://ldap.example.com:389) — the error message names the exact missing key.
  2. For each key in sonar.authenticator.ldap.servers, define sonar.authenticator.ldap.<key>.url.
  3. Check that the value is not blank due to templating/env substitution failures.

Example fix

// before
sonar.authenticator.ldap.servers: server1,server2
sonar.authenticator.ldap.server1.url: ldap://ldap1.example.com
// after: define url for every server
sonar.authenticator.ldap.servers: server1,server2
sonar.authenticator.ldap.server1.url: ldap://ldap1.example.com
sonar.authenticator.ldap.server2.url: ldap://ldap2.example.com
Defensive patterns

Strategy: validation

Validate before calling

String[] keys = config.hasKey("sonar.authenticator.ldap.servers")
  ? config.get("sonar.authenticator.ldap.servers").split(",")
  : new String[]{null};
for (String key : keys) {
  String urlKey = key == null ? "sonar.authenticator.ldap.url" : "sonar.authenticator.ldap." + key + ".url";
  if (!config.hasKey(urlKey) || config.get(urlKey).isBlank()) {
    throw new IllegalStateException("Mandatory LDAP property missing or empty: " + urlKey);
  }
}

Try / catch

try {
  settingsManager.getContextFactories();
} catch (LdapException e) {
  LOG.error("LDAP config error: {}", e.getMessage()); // message names the missing <prefix>.url key
  throw e;
}

Prevention

When it happens

Trigger: Initializing an LDAP context factory (during getContextFactories/setup) when sonar.authenticator.ldap.url (single-server) or sonar.authenticator.ldap.<serverKey>.url (multi-server) is missing, empty, or whitespace-only.

Common situations: Forgot to set ldap.url after enabling LDAP authentication; in multi-server setups one listed server key lacks its .url property; property defined but value accidentally emptied/commented; env-var substitution in sonar.properties yielding empty string.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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