hashicorp/nomad · error

Failed to parse network-interface: %v

Error message

Failed to parse network-interface: %v

What it means

When a client agent sets client.network_interface, the value (which may be a template) is parsed with parseSingleInterfaceTemplate during normalization. Any template rendering error or invalid interface result is reported as 'Failed to parse network-interface' with the underlying cause. Startup stops because the interface is needed to discover the advertise IP.

Source

Thrown at command/agent/config.go:2431

	if err != nil {
		return fmt.Errorf("Failed to parse RPC advertise address: %v", err)
	}
	c.AdvertiseAddrs.RPC = addr

	// Skip serf if server is disabled
	if c.Server != nil && c.Server.Enabled {
		addr, err = normalizeAdvertise(c.AdvertiseAddrs.Serf, c.Addresses.Serf, c.Ports.Serf, c.DevMode)
		if err != nil {
			return fmt.Errorf("Failed to parse Serf advertise address: %v", err)
		}
		c.AdvertiseAddrs.Serf = addr
	}

	// Skip network_interface evaluation if not a client
	if c.Client != nil && c.Client.Enabled && c.Client.NetworkInterface != "" {
		parsed, err := parseSingleInterfaceTemplate(c.Client.NetworkInterface)
		if err != nil {
			return fmt.Errorf("Failed to parse network-interface: %v", err)
		}

		c.Client.NetworkInterface = parsed
	}

	return nil
}

// parseSingleInterfaceTemplate parses a go-sockaddr template and returns an
// error if it doesn't result in a single value.
func parseSingleInterfaceTemplate(tpl string) (string, error) {
	out, err := template.Parse(tpl)
	if err != nil {
		// Typically something like:
		// unable to parse template "{{printfl \"en50\"}}": template: sockaddr.Parse:1: function "printfl" not defined
		return "", err
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Fix the template syntax or interface name in client.network_interface
2. List interfaces on the host (ip link) and use an exact existing name
3. Omit client.network_interface to let the agent auto-detect the private IP
4. Inspect the wrapped %v message for the template error

Example fix

// before
client { network_interface = "{{ GetInterfaceIP \"eth0\"  }" } # malformed template
// after
client { network_interface = "{{ GetInterfaceIP \"eth0\" }}" }

name, err := renderTemplate(cfg.Client.NetworkInterface) // must not error
if err == nil {
	if _, err := net.InterfaceByName(strings.TrimSpace(name)); err != nil {
		// interface missing: fix config before starting agent
	}
}

When it happens

Trigger: client.network_interface containing a template expression that fails (e.g. {{ GetInterfaceIP "ethX" }} on a missing interface), or otherwise unparseable interface input, while client.enabled = true.

Common situations: Container/VM images where the expected interface name differs (ens5 vs eth0); template braces mistyped in HCL; running as client on a host whose primary NIC was renamed.

Understand the failure class

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

Related errors

• template %q evaluated to empty result
• Unable to parse address template %q: %v
• No addresses found, please configure one.
• failed to configure network manager: %v
• failed to initialize network configurator: %v

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