---
title: Configuration Server client properties
sidebar_label: Configuration Server client properties
---

This page documents Java system properties that control how Deephaven processes connect to the Configuration Server. These properties tune connection behavior, load balancing, timeouts, and retry logic.

> [!NOTE]
> These are Java **system properties**, not Deephaven properties file settings. Set them using the `-D` flag when starting a Java process (e.g., `-Dconfiguration.server.load.balancer.policy=round_robin`).

## Connection properties

| Property                                                | Default      | Description                                                                                                                        |
| ------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `configuration.server.load.balancer.policy`             | `pick_first` | gRPC load balancing policy for connecting to configuration servers. See [Load balancer policies](#load-balancer-policies).         |
| `configuration.server.rearrange.hosts`                  | `true`       | Whether to randomly shuffle the order of configuration servers before connecting.                                                  |
| `configuration.server.connection.timeout.millis.single` | `30000`      | Connection timeout in milliseconds when only one configuration server is configured.                                               |
| `configuration.server.connection.timeout.millis.multi`  | `6000`       | Connection timeout in milliseconds when multiple configuration servers are configured. The shorter default allows faster failover. |

## Retry properties

| Property                                 | Default | Description                                                                               |
| ---------------------------------------- | ------- | ----------------------------------------------------------------------------------------- |
| `configuration.server.max.retries.limit` | `60`    | Maximum number of retry attempts for gRPC calls. Set to `0` to disable retries.           |
| `configuration.server.connectTimeoutMs`  | `60000` | Overall timeout in milliseconds for loading configuration from the server.                |
| `configuration.server.retryPauseMs`      | `1000`  | Pause in milliseconds between retry attempts when connecting to the configuration server. |

## Service configuration

| Property                                   | Default                             | Description                                       |
| ------------------------------------------ | ----------------------------------- | ------------------------------------------------- |
| `configuration.server.service.config.json` | `configuration_service_config.json` | Name of the gRPC service configuration JSON file. |

## Load balancer policies

The `configuration.server.load.balancer.policy` property accepts gRPC load balancing policy names:

- **`pick_first`** (default) — Tries configuration servers in order. Connects to the first available server and stays connected. If the connection fails, it moves to the next server. Best for most deployments.
- **`round_robin`** — Maintains connections to all configuration servers and distributes requests across them. Useful for high-availability deployments where you want active connections to all servers.

When `configuration.server.rearrange.hosts` is `true` (the default), the order of servers is randomized before applying the load balancing policy. This helps distribute load across servers even with `pick_first`.

## Examples

### High-availability configuration

To use round-robin load balancing with active connections to all configuration servers:

```bash
java -Dconfiguration.server.load.balancer.policy=round_robin \
     -Dconfiguration.server.connection.timeout.millis.multi=10000 \
     -jar my-application.jar
```

### Troubleshooting connectivity issues

If clients are timing out before reaching the Configuration Server, increase the timeout values:

```bash
java -Dconfiguration.server.connection.timeout.millis.single=60000 \
     -Dconfiguration.server.connectTimeoutMs=120000 \
     -jar my-application.jar
```

### Disabling retries for debugging

To disable automatic retries and see failures immediately:

```bash
java -Dconfiguration.server.max.retries.limit=0 \
     -jar my-application.jar
```

### Kubernetes configuration

In Kubernetes deployments, set these properties via Helm values in your override file. For example, to set the connection timeout in milliseconds when multiple Configuration Servers are configured:

```yaml
process:
  configuration-server:
    jvmArgsUser: "-Dconfiguration.server.connection.timeout.millis.multi=60000"
```

Apply the configuration with `helm upgrade`. For more Helm configuration options, see [Kubernetes configuration settings](../kubernetes/kubernetes-configuration-settings.md).

## Related documentation

- [Configuration Server overview](./configuration-server-overview.md)
- [Configuration overview](./configuration-overview.md)
- [Java process launch configuration](./java-process-launch.md)
- [Kubernetes configuration settings](../kubernetes/kubernetes-configuration-settings.md)
- [etcd](../core-components/etcd.md)