Troubleshoot coordinator high availability#
If you experience issues with coordinator high availability, check the following common issues.
No failover after coordinator failure#
If the active coordinator is down but no standby has been promoted:
Verify standby coordinators are running, reachable, and in the
STANDBYstate.Check Starburst control plane logs for health check failure messages.
Ensure standby coordinators have successful recent health checks.
Confirm health check failures have reached the threshold (3 failures over 10 seconds).
Queries fail during failover#
There is a brief window during failover where no active coordinator exists. Queries you submit during this time might fail. Configure your client application to retry failed queries.
Multiple coordinators marked as DECOMMISSIONED#
If all but one coordinator are in the DECOMMISSIONED state:
Review control plane logs for events with multiple active coordinators.
Restart coordinators in the
DECOMMISSIONEDstate to return them to the high availability (HA) pool as standbys.Check for network issues between the control plane and the coordinators.
Coordinator is marked as GONE#
A coordinator is marked as GONE when the health check detects that the URI
for a registered coordinator now responds with a different instance identifier.
This typically happens after a coordinator restarts and is assigned a new
instance identifier while reusing the same URI (for example, after a Kubernetes
pod restart without a persistent identity).
The stale GONE record is kept in the database for audit purposes but is
excluded from HA management. No action is required. The new coordinator
instance at the same URI registers itself as a STANDBY automatically once it
sends an announcement to the control plane.
Health checks show UNKNOWN status#
If a coordinator’s health status is UNKNOWN:
Check for network issues between the control plane and the coordinators.
Confirm the coordinator’s
/v1/info/stateendpoint is accessible.Check control plane logs for health check failure messages.
Coordinator does not start in managed mode on Helm#
If the coordinator logs the error “Property ‘discovery.uri’ must be equal to
deployment.manager.uri when deployment.mode=MANAGED”, the Helm chart of release
2026.6.0 supplied its own discovery.uri. Set discovery.uri to the same value
as deployment.manager.uri in additionalProperties, for the coordinator and
for the workers. See Helm values for a managed cluster.
Queries fail with an error about missing catalogs#
In managed mode, a worker needs deployment.mode, deployment.manager.uri, and
discovery.uri, like the coordinator. A worker without them uses the static
catalog manager, and a query that needs a catalog from the control plane fails
with the error “Missing catalogs”. The message appears in the failed query, and
control plane logs show nothing for it. Add the properties to every worker, and
restart it. See Configure SEP workers.
The coordinator logs announce errors with HTTP status 409#
If the coordinator logs “Failed to announce node state”, with HTTP status 409, and the control plane logs that the backend does not use discovery, the cluster is registered without discovery. Edit the cluster in the Clusters pane, and turn on discovery. See Register the cluster with discovery.
A failover request fails with DiscoveryDisabled#
The cluster does not use discovery, so the control plane does not manage its coordinators. Register the cluster with discovery, and try again. For the other error codes, see Trigger a hard failover.
Queries reach the standby coordinator#
If you send queries to the Kubernetes Service of the cluster, the connection can reach the standby coordinator. The Service selects both coordinators, and it cannot tell the active coordinator from the standby coordinator. Send your queries through the control plane.
Both coordinators stop during a Helm upgrade#
The coordinator Deployment of the Helm chart uses the Recreate strategy, so a
Helm upgrade stops both coordinators. Coordinator high availability does not
cover upgrades. Plan the upgrade for a time when the cluster can be
unavailable.
The control plane keeps calling the old address of a coordinator#
After a coordinator restarts, the control plane can keep calling the old address of the coordinator for several minutes, and health checks and metadata harvests can fail. Restart the control plane pods to fix it. This is a known issue in release 2026.6.0.