hashicorp/nomad · error

id must be a uuid: %w

Error message

id must be a uuid: %w

What it means

RaftPeerRequest.validateID failed to parse the supplied Raft server ID as a UUID; when the ID field is used it must be a valid UUID.

Source

Thrown at nomad/structs/operator.go:99

	// 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)
	}
	return nil
}

type LeadershipTransferResponse struct {
	From RaftIDAddress // Server yielding leadership
	To   RaftIDAddress // Server obtaining leadership
	Noop bool          // Was the transfer a non-operation
	Err  error         // Non-nil if there was an error while transferring leadership
}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Use the server's UUID as printed by `nomad operator raft list-peers`
2. Pass the Address instead of a malformed ID

When it happens

Trigger: Thrown at nomad/structs/operator.go:99 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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