hashicorp/nomad · error

invalid address mode %q

Error message

invalid address mode %q

What it means

GetAddress switches on the service's address_mode (host, driver, alloc, alloc_ipv6). The default branch enforces invariants: job validation should have rejected unknown modes earlier, so hitting this error at runtime indicates an unrecognized address mode string reached the resolver anyway.

Source

Thrown at client/serviceregistration/address.go:176

			}

			return getAddressPort(addressMode, netStatus, port.Value)
		}

		// Check if port is a literal number
		port, err := strconv.Atoi(portLabel)
		if err != nil {
			// User likely specified wrong port label here
			return "", 0, fmt.Errorf("invalid port %q: port label not found or is not numeric", portLabel)
		}
		if port <= 0 {
			return "", 0, fmt.Errorf("invalid port: %q: port must be >0", portLabel)
		}

		return getAddressPort(addressMode, netStatus, port)
	default:
		// Shouldn't happen due to validation, but enforce invariants
		return "", 0, fmt.Errorf("invalid address mode %q", addressMode)
	}
}

// getAddressPort is a helper function to return the IPv6 or IPv4 address based on the addressMode
func getAddressPort(addressMode string, netStatus *structs.AllocNetworkStatus, port int) (string, int, error) {
	if addressMode == structs.AddressModeAllocIPv6 {
		return netStatus.AddressIPv6, port, nil
	}

	return netStatus.Address, port, nil
}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Correct address_mode in the job spec to one of: host, driver, alloc, alloc_ipv6
2. Re-run nomad job validate / submit through the API so validation rejects bad modes upfront
3. Ensure client and server Nomad versions are consistent (mode support differs across versions)

Example fix

// before
service {
  name = "web"
  address_mode = "allocation"
}
// after
service {
  name = "web"
  address_mode = "alloc"
}

var validAddressModes = map[string]bool{"host": true, "driver": true, "alloc": true, "alloc_ipv6": true}
if !validAddressModes[service.AddressMode] {
    return fmt.Errorf("service %q: invalid address_mode %q", service.Name, service.AddressMode)
}

func isValidAddressMode(m string) bool {
    switch m {
    case "host", "driver", "alloc", "alloc_ipv6":
        return true
    }
    return false
}

ip, port, err := GetAddress(addr, mode, portLabel, networks, dn, ports, netStatus)
if err != nil && strings.Contains(err.Error(), "invalid address mode") {
    logger.Error("unknown address mode reached resolver; fix job spec", "mode", mode)
    return err
}

When it happens

Trigger: An address mode value other than "host", "driver", "alloc", or "alloc_ipv6" is passed to GetAddress — normally only possible if validation was bypassed, an API client submitted an unvalidated job, or a new/unknown mode comes from an older/newer binary mismatch.

Common situations: Submitting jobs via the raw API skipping server-side validation; typo'd address_mode in generated/templated job specs; mixing Nomad versions where an address_mode value is not recognized by the client binary.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• unknown service registration provider: %q
• unknown service registration provider for update: %q
• service registration not found
• cannot use address_mode="alloc": no allocation network statu
• invalid port %q: port label not found or is not numeric

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