hashicorp/nomad · error

an address or id is required for the destination peer

Error message

an address or id is required for the destination peer

What it means

raftTransferLeadership validates that exactly one of -peer-address or -peer-id is provided before calling the Operator API to transfer Raft leadership. When both are empty it returns this error, since the destination peer cannot be determined. The command surfaces it via `Error transferring leadership to peer:`.

Source

Thrown at command/operator_raft_leadership_transfer.go:107

	}
	operator := client.Operator()

	if err := raftTransferLeadership(peerAddress, peerID, operator); err != nil {
		c.Ui.Error(fmt.Sprintf("Error transferring leadership to peer: %v", err))
		return 1
	}
	if peerAddress != "" {
		c.Ui.Output(fmt.Sprintf("Transferred leadership to peer with address %q", peerAddress))
	} else {
		c.Ui.Output(fmt.Sprintf("Transferred leadership to peer with id %q", peerID))
	}

	return 0
}

func raftTransferLeadership(address, id string, operator *api.Operator) error {
	if len(address) == 0 && len(id) == 0 {
		return fmt.Errorf("an address or id is required for the destination peer")
	}
	if len(address) > 0 && len(id) > 0 {
		return fmt.Errorf("cannot give both an address and id")
	}

	// Try to perform the leadership transfer.
	if len(address) > 0 {
		if err := operator.RaftTransferLeadershipByAddress(address, nil); err != nil {
			return err
		}
	} else {
		if err := operator.RaftTransferLeadershipByID(id, nil); err != nil {
			return err
		}
	}

	return nil
}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Pass exactly one destination flag, e.g. -peer-id="<server-id>" or -peer-address="10.0.0.5:4647".
2. Look up valid peer values with `nomad operator raft list-peers` before transferring.
3. In scripts, fail fast if the resolved peer variable is empty instead of invoking the command with blank flags.

Example fix

// before
nomad operator raft transfer-leadership
// after
nomad operator raft transfer-leadership -peer-id="f0b1d0cc-..."

if (peerAddress == "") == (peerID == "") {
    return fmt.Errorf("provide exactly one of -peer-address or -peer-id")
}

if err := raftTransferLeadership(addr, id, operator); err != nil {
    c.Ui.Error(fmt.Sprintf("Error transferring leadership to peer: %v", err))
    return 1
}

When it happens

Trigger: Running `nomad operator raft transfer-leadership` with neither -peer-address nor -peer-id set.

Common situations: Forgetting both flags entirely, or setting them via a script/config where empty variables expand to blank values (e.g. -peer-address="" -peer-id="").

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• A template must be supplied using '-template' when using go-
• Invalid value for "-out"; valid values are [go-template, hcl
• either ID or Address must be set
• Group %v not found within job
• cannot give both an address and id

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