theonedev/onedev · critical · RuntimeException

Unable to discover cluster ip from database connection url:

Error message

Unable to discover cluster ip from database connection url: 

What it means

When clustering is enabled, ServerConfig must determine the server's cluster IP. If no cluster ip is configured explicitly, it tries to derive one from the hosts referenced by the database connection URL; if none of those hosts is reachable/matches, it throws this RuntimeException.

Source

Thrown at server-core/src/main/java/io/onedev/server/ServerConfig.java:146

							dbPorts.put(StringUtils.substringBefore(part, ":"), 
									parseInt(StringUtils.substringAfter(part, ":")));
						} else {
							dbPorts.put(part, 5432);
						}
					}
				}

				for (var entry: dbPorts.entrySet()) {
					try (Socket socket = new Socket()) {
						socket.connect(new InetSocketAddress(entry.getKey(), entry.getValue()));
						clusterIp = socket.getLocalAddress().getHostAddress();
						break;
					} catch (Exception e) {
						logger.warn(String.format("Connection failed (host: %s, port: %d)", entry.getKey(), entry.getValue()), e);
					}
				}
				if (StringUtils.isBlank(clusterIp)) 
					throw new RuntimeException("Unable to discover cluster ip from database connection url: " + dbUrl);
			}
		}
		this.clusterIp = clusterIp;

		String clusterPortStr = System.getenv(PROP_CLUSTER_PORT);
		if (StringUtils.isBlank(clusterPortStr))
			clusterPortStr = props.getProperty(PROP_CLUSTER_PORT);
		if (StringUtils.isBlank(clusterPortStr))
			clusterPort = 5710;
		else
			clusterPort = parseInt(clusterPortStr.trim());
	}

	public int getHttpPort() {
		return httpPort;
	}

	public int getSshPort() {

View on GitHub (pinned to d44925c47c)

Solutions

1. Set the cluster ip explicitly via the CLUSTER_IP environment variable (PROP_CLUSTER_IP) so discovery from the db url is unnecessary.
2. Verify network reachability to every host in the jdbc url from this server (telnet/nc the db host:port).
3. Check that the jdbc url is in an expected format containing resolvable host(s); fix malformed urls.
4. If clustering is not intended, remove cluster-related env/properties so the discovery path is not taken.

Example fix

// before
docker run onedev  # no CLUSTER_IP set
// after
docker run -e CLUSTER_IP=10.0.0.5 onedev

if (System.getenv("CLUSTER_PORT") != null && System.getenv("CLUSTER_IP") == null) {
    // ensure explicit cluster ip is provided to skip db-url discovery
    throw new IllegalStateException("Set CLUSTER_IP when clustering is enabled");
}

try {
    new ServerConfig(...);
} catch (RuntimeException e) {
    if (e.getMessage().startsWith("Unable to discover cluster ip")) {
        // fall back: set CLUSTER_IP env var and restart
    }
}

When it happens

Trigger: Starting OneDev with clustering enabled (cluster port/prop set) without PROP_CLUSTER_IP set, and the JDBC URL hosts cannot be contacted or none of them yields an address, so clusterIp remains blank after the host probing loop.

Common situations: Kubernetes/container deployments where the DB hostname is not resolvable from the node, a firewall blocking the attempted connections, a jdbc url format the discovery logic cannot parse, or forgetting to set CLUSTER_IP env var.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• Unrecognized command:
• Upload project not found:
• Time tracking needs to be enabled for the project
• Link spec not found: ${linkName}
• Loopback address not allowed for target docker image of push

AI-assisted analysis of theonedev/onedev@d44925c47c (2026-09-06). Data as JSON: /api/errors/8445da68539c0d23. Report an issue: GitHub.