rqlite/rqlite · critical

failed to start discovery service: %s

Error message

failed to start discovery service: %s

What it means

When -disco-mode is consul-kv or etcd-kv, rqlited builds a discovery service client via createDiscoService. If that construction fails (bad endpoint, credentials, or client initialization error), node startup aborts with this message. The discovery service is required for the node to find/register with the cluster, so rqlited refuses to continue in a degraded state.

Source

Thrown at cmd/rqlited/main.go:696

			provider = dns.NewWithPort(dnsCfg, cfg.RaftPort())

		} else {
			dnssrvCfg, err := dnssrv.NewConfigFromReader(rc)
			if err != nil {
				return fmt.Errorf("error reading DNS configuration: %s", err.Error())
			}
			provider = dnssrv.New(dnssrvCfg)
		}

		bs := cluster.NewBootstrapper(provider, client)
		bs.SetCredentials(cluster.CredentialsFor(credStr, cfg.JoinAs))
		httpServ.RegisterStatus("disco", provider)
		return bs.Boot(ctx, str.ID(), cfg.RaftAdv, clusterSuf, bootDoneFn, cfg.BootstrapExpectTimeout)

	case DiscoModeEtcdKV, DiscoModeConsulKV:
		discoService, err := createDiscoService(cfg, str)
		if err != nil {
			return fmt.Errorf("failed to start discovery service: %s", err.Error())
		}
		// Safe to start reporting before doing registration. If the node hasn't bootstrapped
		// yet, or isn't leader, reporting will just be a no-op until something changes.
		go discoService.StartReporting(cfg.NodeID, cfg.HTTPURL(), cfg.RaftAdv)
		httpServ.RegisterStatus("disco", discoService)

		if hasPeers {
			log.Printf("preexisting node configuration detected, not registering with discovery service")
			return nil
		}
		log.Println("no preexisting nodes, registering with discovery service")

		leader, addr, err := discoService.Register(str.ID(), cfg.HTTPURL(), cfg.RaftAdv)
		if err != nil {
			return fmt.Errorf("failed to register with discovery service: %s", err.Error())
		}
		if leader {
			log.Println("node registered as leader using discovery service")

View on GitHub (pinned to 7586a4d1bd)

Solutions

1. Verify the Consul/Etcd endpoint in the disco config is correct and reachable (curl the health endpoint).
2. Check credentials/ACL tokens configured for the KV store are valid and not expired.
3. Start the discovery service or switch to another clustering method (explicit -join addresses or DNS discovery).

Example fix

// before
rqlited -disco-mode consul-kv -disco-config consul.cfg   # consul at wrong host
// after
rqlited -disco-mode consul-kv -disco-config consul.cfg   # config points to http://127.0.0.1:8500, consul running

conn, err := net.DialTimeout("tcp", consulHostPort, 2*time.Second)
if err != nil {
    return fmt.Errorf("discovery service unreachable at %s: %v", consulHostPort, err)
}

When it happens

Trigger: Running with -disco-mode consul-kv or etcd-kv when createDiscoService returns an error: unreachable or malformed Consul/Etcd endpoint, missing API key/credentials, unsupported scheme, or constructor failure inside the disco package.

Common situations: Consul/Etcd not running or wrong host:port configured; network/firewall blocking the KV store; expired or invalid ACL token; typo in -disco-config endpoint.

Related errors

• failed to register with discovery service: %s
• HTTP and Raft addresses must differ
• failed to download auto-restore file: %s
• advertised HTTP address is not routable (%s), specify it via
• create Consul config: %s

AI-assisted analysis of rqlite/rqlite@7586a4d1bd (2026-09-03). Data as JSON: /api/errors/e1f2332aa38f4be7. Report an issue: GitHub.