rqlite/rqlite · error

raft bind address not valid

Error message

raft bind address not valid

What it means

Config.Validate (cmd/rqlited/flags.go:128) applies net.SplitHostPort to -raft-addr; a parse failure yields this error, while a non-numeric port yields the related 'raft bind port not valid'. The Raft bind address must be a valid host:port since the Raft layer listens there.

Source

Thrown at cmd/rqlited/flags.go:128

	if strings.HasPrefix(strings.ToLower(c.HTTPAddr), "http") ||
		strings.HasPrefix(strings.ToLower(c.HTTPAdv), "http") {
		return errors.New("HTTP options should not include protocol (http:// or https://)")
	}
	if _, _, err := net.SplitHostPort(c.HTTPAddr); err != nil {
		return errors.New("HTTP bind address not valid")
	}

	hadv, _, err := net.SplitHostPort(c.HTTPAdv)
	if err != nil {
		return errors.New("HTTP advertised HTTP address not valid")
	}
	if addr := net.ParseIP(hadv); addr != nil && addr.IsUnspecified() {
		return fmt.Errorf("advertised HTTP address is not routable (%s), specify it via -%s or -%s",
			hadv, HTTPAddrFlag, HTTPAdvAddrFlag)
	}

	if _, rp, err := net.SplitHostPort(c.RaftAddr); err != nil {
		return errors.New("raft bind address not valid")
	} else if _, err := strconv.Atoi(rp); err != nil {
		return errors.New("raft bind port not valid")
	}

	radv, rp, err := net.SplitHostPort(c.RaftAdv)
	if err != nil {
		return errors.New("raft advertised address not valid")
	}
	if addr := net.ParseIP(radv); addr != nil && addr.IsUnspecified() {
		return fmt.Errorf("advertised Raft address is not routable (%s), specify it via -%s or -%s",
			radv, RaftAddrFlag, RaftAdvAddrFlag)
	}
	if _, err := strconv.Atoi(rp); err != nil {
		return errors.New("raft advertised port is not valid")
	}

	if c.RaftAdv == c.HTTPAdv {
		return errors.New("advertised HTTP and Raft addresses must differ")

View on GitHub (pinned to 7586a4d1bd)

Solutions

1. Provide a full host:port value, e.g. -raft-addr=localhost:4002
2. Ensure the port is numeric
3. Bracket IPv6 hosts, e.g. -raft-addr=[::1]:4002

Example fix

// before
rqlited -raft-addr=raft://localhost:4002
// after
rqlited -raft-addr=localhost:4002

_, port, err := net.SplitHostPort(raftAddr)
if err != nil {
    return fmt.Errorf("-raft-addr must be host:port, got %q", raftAddr)
}
if _, err := strconv.Atoi(port); err != nil {
    return fmt.Errorf("raft bind port must be numeric, got %q", port)
}

if err := cfg.Validate(); err != nil {
    log.Fatalf("invalid flags: %v", err)
}

When it happens

Trigger: Starting rqlited with -raft-addr missing its port, malformed, or containing a scheme like raft://host:port.

Common situations: Forgetting the port (e.g. -raft-addr=localhost); using a named service port instead of a number; copy-pasting a URL into the address flag.

Related errors

• HTTP bind address not valid
• HTTP advertised HTTP address not valid
• HTTP and Raft addresses must differ
• HTTP options should not include protocol (http:// or https:/
• join address %s appears to be serving HTTP when it should be

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