hashicorp/nomad · error

failed querying self endpoint: %s

Error message

failed querying self endpoint: %s

What it means

api/agent.go's Agent.Self() queries the local agent's /v1/agent/self endpoint; any error from the HTTP query is wrapped as "failed querying self endpoint: %s". This typically means the agent is unreachable, not running, or returned a non-2xx response.

Source

Thrown at api/agent.go:59

	// Prune indicates whether to remove a node from the list of members
	Prune bool
}

// Agent returns a new agent which can be used to query
// the agent-specific endpoints.
func (c *Client) Agent() *Agent {
	return &Agent{client: c}
}

// Self is used to query the /v1/agent/self endpoint and
// returns information specific to the running agent.
func (a *Agent) Self() (*AgentSelf, error) {
	var out *AgentSelf

	// Query the self endpoint on the agent
	_, err := a.client.query("/v1/agent/self", &out, nil)
	if err != nil {
		return nil, fmt.Errorf("failed querying self endpoint: %s", err)
	}

	// Populate the cache for faster queries
	a.populateCache(out)

	return out, nil
}

// populateCache is used to insert various pieces of static
// data into the agent handle. This is used during subsequent
// lookups for the same data later on to save the round trip.
func (a *Agent) populateCache(self *AgentSelf) {
	if a.nodeName == "" {
		a.nodeName = self.Member.Name
	}
	if a.datacenter == "" {
		if val, ok := self.Config["Datacenter"]; ok {
			a.datacenter, _ = val.(string)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Verify the Consul agent is running and the client address/port are correct (e.g. 127.0.0.1:8500).
2. Check the wrapped error: 403 means set a valid ACL token via config ACLToken; connection refused means fix networking.
3. Test the endpoint manually with `curl http://<agent>:8500/v1/agent/self`.
4. If relying on NodeName/Datacenter/Region, ensure agent connectivity before caching.

Example fix

// before
client, _ := api.NewClient(api.DefaultConfig())
name, err := client.Agent().NodeName() // fails: wrong port
// after
cfg := api.DefaultConfig()
cfg.Address = "127.0.0.1:8500"
cfg.Token = os.Getenv("CONSUL_HTTP_TOKEN")
client, _ := api.NewClient(cfg)
name, err := client.Agent().NodeName()

// probe the agent before calling Self
dialTimeout := 2 * time.Second
conn, err := net.DialTimeout("tcp", "127.0.0.1:8500", dialTimeout)
if err != nil {
    return fmt.Errorf("consul agent not reachable: %w", err)
}
conn.Close()

self, err := client.Agent().Self()
if err != nil {
    if strings.Contains(err.Error(), "failed querying self endpoint") {
        // check agent health / ACL token, optionally retry once
        return retryOrFallback()
    }
    return err
}

When it happens

Trigger: Calling Agent.Self() (directly or via NodeName(), Datacenter(), Region(), which call Self) when the Consul agent HTTP API is unreachable or returns an error status.

Common situations: Agent not running or wrong address/port in the Consul client config; ACL token lacking agent read permissions (403); firewall/network issues; container service discovery pointing at the wrong host.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

• failed joining: %s
• Nomad Enterprise only endpoint
• Unknown log level
• error retrieving supported Envoy versions from Consul: %w
• error getting snapshot from previous alloc %q: %w

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