thanos-io/thanos · error

endpoint address must be set

Error message

endpoint address must be set

What it means

Endpoint.UnmarshalJSON validates each endpoint after unmarshaling and rejects it when the required Address field is empty. Every hashring endpoint must have an address (host:port of the receive node); this fail-fast validation prevents silently routing series to an unaddressable endpoint.

Solutions

1. Add a non-empty `address` field to every endpoint in the hashring config
2. Check for key typos — the field must be exactly `address` (with optional `capnproto_address` additionally)
3. Fix the template/renderer so the address variable is always populated
4. Validate the full hashring JSON before applying it

Example fix

// before
{"endpoints": [{"capnproto_address": "recv-0:10991"}]}
// after
{"endpoints": [{"address": "recv-0:10901", "capnproto_address": "recv-0:10991"}]}

func validEndpoint(e Endpoint) bool { return e.Address != "" }
// before applying config:
for _, h := range hashrings {
	for _, e := range h.Endpoints {
		if e.Address == "" { return errors.New("endpoint missing address") }
	}
}

if err := json.Unmarshal(data, &cfg); err != nil {
	if strings.Contains(err.Error(), "endpoint address must be set") {
		// fix the endpoint entry and retry
	}
}

When it happens

Trigger: Unmarshaling a hashring config where an endpoint object omits the `address` key or sets it to "" — e.g. {"endpoints": [{"capnproto_address": "..."}]} with no address.

Common situations: Template rendering with an empty variable for the address; renamed/mistyped key (`addr`, `host`) so Address stays at its zero value; partial endpoint entries added by automation.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• unsupported format for label
• --auto-gomemlimit.ratio must be greater than 0 and less…
• unable to unmarshal config content
• endpoint
• unable to validate endpoints

AI-assisted analysis of thanos-io/thanos@35b8b99117 (2026-09-07). Data as JSON: /api/errors/253519555490c564. Report an issue: GitHub.

Appendix: source

Thrown at pkg/receive/config.go:85

	Address          string `json:"address"`
	CapNProtoAddress string `json:"capnproto_address"`
	AZ               string `json:"az"`
}

func (e Endpoint) String() string {
	return fmt.Sprintf("addr: %s, capnp_addr: %s, az: %s", e.Address, e.CapNProtoAddress, e.AZ)
}

func (e *Endpoint) HasAddress(addr string) bool {
	return e.Address == addr || e.CapNProtoAddress == addr
}

func (e *Endpoint) UnmarshalJSON(data []byte) error {
	if err := e.unmarshal(data); err != nil {
		return err
	}
	if e.Address == "" {
		return errors.New("endpoint address must be set")
	}

	// If the Cap'n proto address is not set, initialize it
	// to the existing address using the default cap'n proto server port.
	if e.CapNProtoAddress != "" {
		return nil
	}
	if parts := strings.SplitN(e.Address, ":", 2); len(parts) <= 2 {
		e.CapNProtoAddress = parts[0] + ":" + DefaultCapNProtoPort
	}
	return nil
}

func (e *Endpoint) unmarshal(data []byte) error {
	// First try to unmarshal as a string.
	err := json.Unmarshal(data, &e.Address)
	if err == nil {
		return nil

View on GitHub (pinned to 35b8b99117)