hashicorp/nomad · error

either ID or Address must be set

Error message

either ID or Address must be set

What it means

RaftPeerRequest.Validate requires exactly one of the peer ID or peer Address to be set; both empty or both set is invalid because the RPC cannot unambiguously identify the peer to operate on. It is used by operator raft transfer-leadership / peer-removal APIs.

Source

Thrown at nomad/structs/operator.go:89

	ID raft.ServerID

	// WriteRequest holds the Region for this request.
	WriteRequest
}

// RaftPeerRequest is used by the Operator endpoint to apply a Raft
// operation on a specific Raft peer by its peer ID or address in the form of
// "IP:port".
type RaftPeerRequest struct {
	// RaftIDAddress contains an ID and Address field to identify the target
	RaftIDAddress
	// WriteRequest holds the Region for this request.
	WriteRequest
}

func (r *RaftPeerRequest) Validate() error {
	if (r.ID == "" && r.Address == "") || (r.ID != "" && r.Address != "") {
		return errors.New("either ID or Address must be set")
	}
	if r.ID != "" {
		return r.validateID()
	}
	return r.validateAddress()
}

func (r *RaftPeerRequest) validateID() error {
	if _, err := uuid.ParseUUID(string(r.ID)); err != nil {
		return fmt.Errorf("id must be a uuid: %w", err)
	}
	return nil
}

func (r *RaftPeerRequest) validateAddress() error {
	if _, err := netip.ParseAddrPort(string(r.Address)); err != nil {
		return fmt.Errorf("address must be in IP:port format: %w", err)
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set exactly one of request.ID or request.Address
2. If both are known, pick ID (preferred) and clear Address
3. Fix the CLI/HTTP call to pass only one peer identifier

Example fix

// before
req := &structs.RaftPeerRequest{ID: "abc-123", Address: "10.0.0.5:4647"}
// after
req := &structs.RaftPeerRequest{ID: "abc-123"}

if (req.ID == "" && req.Address == "") || (req.ID != "" && req.Address != "") {
    return fmt.Errorf("set exactly one of RaftPeerRequest.ID or .Address")
}

func hasOnePeerIdentifier(id, addr string) bool { return (id == "") != (addr == "") }

if err := req.Validate(); err != nil {
    if strings.Contains(err.Error(), "either ID or Address") {
        // correct the request and retry once
    }
}

When it happens

Trigger: Calling OperatorRaftTransferLeadership or TransferLeadershipToPeer with a RaftPeerRequest where ID and Address are both empty, or both non-empty.

Common situations: Operator CLI/operator HTTP API calls to transfer Raft leadership without specifying -peer-id or -peer-address, or specifying both; programmatic clients building the request with leftover fields.

Related errors

• an address or id is required for the destination peer
• unsupported raft log store backend: %q
• missing secret ID
• namespace cannot contain template delimiters or parenthesis
• wait config is nil or empty

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/feaf1dfb1b0d6362. Report an issue: GitHub.