SonarSource/sonarqube · error · MessageException

Property %s must not contain a loopback address: %s

Error message

Property %s must not contain a loopback address: %s

What it means

Cluster nodes must advertise routable addresses. ensureNotLoopbackAddresses filters the parsed host set of a cluster property through network.isLoopback and throws a MessageException naming the property and every loopback host found, because localhost/127.0.0.1/::1 addresses cannot be reached by other cluster members.

Source

Thrown at server/sonar-main/src/main/java/org/sonar/application/config/ClusterSettings.java:208

    if (!violations.isEmpty()) {
      throw new MessageException(format("Properties [%s] are not allowed when running SonarQube in cluster mode.", String.join(", ", violations)));
    }
  }

  private static void ensureNotH2(Props props) {
    String jdbcUrl = props.value(JDBC_URL.getKey());
    String trimmedJdbcUrl = jdbcUrl == null ? null : jdbcUrl.trim();
    if (trimmedJdbcUrl == null || trimmedJdbcUrl.isEmpty() || trimmedJdbcUrl.startsWith("jdbc:h2:")) {
      throw new MessageException("Embedded database is not supported in cluster mode");
    }
  }

  private void ensureNotLoopbackAddresses(Property property, Set<AddressAndPort> hostAndPorts) {
    Set<AddressAndPort> loopbackAddresses = hostAndPorts.stream()
      .filter(t -> network.isLoopback(t.getHost()))
      .collect(toSet());
    if (!loopbackAddresses.isEmpty()) {
      throw new MessageException(format("Property %s must not contain a loopback address: %s", property.getKey(),
        loopbackAddresses.stream().map(AddressAndPort::getHost).sorted().collect(Collectors.joining(", "))));
    }
  }

  private void ensureLocalButNotLoopbackAddress(Property property, AddressAndPort addressAndPort) {
    String host = addressAndPort.getHost();
    if (!network.isLocal(host) || network.isLoopback(host)) {
      throw new MessageException(format("Property %s must be a local non-loopback address: %s", property.getKey(), addressAndPort.getHost()));
    }
  }

  private static void ensureEitherPortsAreProvidedOrOnlyHosts(Property property, Set<AddressAndPort> addressAndPorts) {
    Set<AddressAndPort> hostsWithoutPort = addressAndPorts.stream()
      .filter(t -> !t.hasPort())
      .collect(toSet());
    if (!hostsWithoutPort.isEmpty() && hostsWithoutPort.size() != addressAndPorts.size()) {
      throw new MessageException(format("Entries in property %s must not mix 'host:port' and 'host'. Provide hosts without port only or hosts with port only.", property.getKey()));
    }

View on GitHub (pinned to 184c821202)

Solutions

1. Replace the loopback host with the node's real, routable IP or DNS name in the property named in the message.
2. For multi-node clusters ensure each node advertises an address reachable by peers (e.g. the pod/service IP in Kubernetes).
3. If the host is a name, verify it resolves to a non-loopback address on the network (check /etc/hosts for entries mapping the name to 127.0.0.1).

Example fix

// before (conf/sonar.properties)
sonar.cluster.node.host=127.0.0.1

// after
sonar.cluster.node.host=192.168.1.10

// shell: reject loopback hosts in cluster properties
for h in $(grep -E '^sonar\.cluster\.' conf/sonar.properties | cut -d= -f2 | tr ',' ' '); do
  case "$h" in localhost|127.*|::1|0:0:0:0:0:0:0:1) echo "Loopback host not allowed: $h"; exit 1;; esac
done

When it happens

Trigger: Called from checkForApplicationNode, checkClusterSearchHosts, and checkClusterEsHosts when properties like sonar.cluster.node.host, sonar.cluster.search.hosts, or sonar.cluster.es.hosts contain a host that resolves to a loopback address.

Common situations: Setting sonar.cluster.node.host=localhost or 127.0.0.1 in sonar.properties; using hostname 'localhost' in container configs where the operator assumed the service DNS name; template defaults never overridden per node.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Address in property %s is not a valid address: %s
• Property %s must be a local non-loopback address: %s
• Failed to validate configuration, check URL and Private Key
• Could not validate GitLab write permission. Got an unexpecte
• Forbidden access to GitLab. Verify your token's permissions

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