SonarSource/sonarqube · error · MessageException

Property must be a local non-loopback address

Error message

Property %s must be a local non-loopback address: %s

What it means

Some cluster properties must point at an address bound to the local machine but not to loopback. ensureLocalButNotLoopbackAddress checks the single AddressAndPort via network.isLocal and network.isLoopback and throws MessageException when the host is either not local to this machine or is a loopback address.

Solutions

1. Set the property to an IP/DNS name actually assigned to this machine's network interface (e.g. the pod IP in Kubernetes, or output of 'ip addr').
2. Avoid localhost/127.0.0.1 even though it is 'local' — loopback is explicitly rejected.
3. In containers, ensure the address is valid inside the container's namespace, not the host's.

Example fix

// before (conf/sonar.properties)
sonar.cluster.node.host=192.168.1.99  # another node's IP

// after
sonar.cluster.node.host=192.168.1.10  # this node's own IP

// shell: the node host must be one of this machine's own non-loopback addresses
host=$(grep -E '^sonar\.cluster\.node\.host=' conf/sonar.properties | cut -d= -f2)
ip -o addr show | grep -qw "$host" || echo "sonar.cluster.node.host=$host is not a local interface address"

When it happens

Trigger: Called from checkForSearchNode and checkClusterNodeHost for properties such as sonar.cluster.node.host and the search node's host: it throws when network.isLocal(host) is false (host not bound to this machine) or network.isLoopback(host) is true (localhost/127.0.0.1).

Common situations: Pointing sonar.cluster.node.host at another node's IP by copy-paste; using 'localhost' on a search node; running in a container where the configured IP belongs to the host machine but not the container network namespace.

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 is not a valid address
• Property must not contain a loopback address
• Can not resolve host [
• Can not resolve host [. Please check network settings and…
• Could not validate GitLab write permission. Got an…

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

Appendix: source

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

    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()));
    }
  }

  private static class AddressAndPort {
    private static final int NO_PORT = -1;

    /**
     * the host from setting, can be a hostname or an IP address
     */

View on GitHub (pinned to 184c821202)