hashicorp/nomad · error

Failed to parse server members, members==nil

Error message

Failed to parse server members, members==nil

What it means

filterServerMembers filters Nomad server member names from an api.ServerMembers response during `nomad operator debug` agent collection. If the response's Members slice is nil — meaning the /v1/agent/members call returned nothing parseable — the function cannot proceed and returns this error. It signals an empty/failed server-members API response rather than a filtering problem.

Source

Thrown at command/operator_debug.go:1844

		f, err := os.Open(file)
		if err != nil {
			return err
		}

		if _, err := io.Copy(tw, f); err != nil {
			return err
		}

		f.Close()

		return nil
	})
}

// filterServerMembers returns a slice of server member names matching the search criteria
func filterServerMembers(serverMembers *api.ServerMembers, serverIDs string, region string) (membersFound []string, err error) {
	if serverMembers.Members == nil {
		return nil, fmt.Errorf("Failed to parse server members, members==nil")
	}

	prefixes := stringToSlice(serverIDs)

	// "leader" is a special case which Nomad handles in the API.  If "leader"
	// appears in serverIDs, add it to membersFound and remove it from the list
	// so that it isn't processed by the range loop
	if slices.Contains(prefixes, "leader") {
		membersFound = append(membersFound, "leader")
		helper.RemoveEqualFold(&prefixes, "leader")
	}

	for _, member := range serverMembers.Members {
		// If region is provided it must match exactly
		if region != "" && member.Tags["region"] != region {
			continue
		}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Verify the target Nomad address is a reachable server (or agent that can proxy): curl $NOMAD_ADDR/v1/agent/members
2. Check NOMAD_ADDR and any ACL token; ensure the token has agent:read / node listing permissions
3. Check Nomad client and server versions for API compatibility; upgrade the CLI to match the cluster
4. Re-run debug; if it persists, inspect server logs for failures on the members endpoint

// validate connectivity and response before filtering
resp, err := client.Agent().Members()
if err != nil {
    return fmt.Errorf("members query failed: %w", err)
}
if resp == nil || resp.Members == nil || len(resp.Members) == 0 {
    return errors.New("no server members returned; check NOMAD_ADDR and ACLs")
}

func hasMembers(m *api.ServerMembers) bool {
    return m != nil && m.Members != nil && len(m.Members) > 0
}

members, err := filterServerMembers(resp, serverIDs, region)
if err != nil {
    if strings.Contains(err.Error(), "members==nil") {
        log.Println("empty members response: verify NOMAD_ADDR points to a reachable server and ACL token grants agent:read")
    }
    return err
}

When it happens

Trigger: api.Agent().Members() returned a ServerMembers with a nil Members slice — the agent members endpoint returned an empty body or a response that did not deserialize into members.

Common situations: Querying a Nomad agent whose HTTP API is unreachable or returning an error body, ACL tokens blocking the members endpoint, mismatched client/server API versions, or pointing debug at a client-only node context where member data is empty.

Understand the failure class

Background: "empty response", "returned no data", "empty embeddings": what HTTP 200-with-empty-body errors mean across libraries — this error's family across 36 libraries.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• unknown task name %q
• error retrieving supported Envoy versions from Consul: %w
• node not found: %s
• allocation not found
• Error restarting allocation %q: %s

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