What causes "missing mask: %v" in slackhq/nebula?

Add a `mask: ` key with a valid CIDR string to the entry

missing mask: %v

Error message

missing mask: %v

What it means

Every calculated_remotes entry must include a `mask` key; newCalculatedRemotesEntryFromConfig throws this when rawMap["mask"] is absent or explicitly null. Without a mask the library cannot compute the calculated remote address and prints the whole entry map to help locate the offender.

Source

Thrown at calculated_remote.go:134

		c, err := newCalculatedRemotesEntryFromConfig(cidr, e)
		if err != nil {
			return nil, fmt.Errorf("calculated_remotes entry: %w", err)
		}
		l = append(l, c)
	}

	return l, nil
}

func newCalculatedRemotesEntryFromConfig(cidr netip.Prefix, raw any) (*calculatedRemote, error) {
	rawMap, ok := raw.(map[string]any)
	if !ok {
		return nil, fmt.Errorf("invalid type: %T", raw)
	}

	rawValue := rawMap["mask"]
	if rawValue == nil {
		return nil, fmt.Errorf("missing mask: %v", rawMap)
	}
	rawMask, ok := rawValue.(string)
	if !ok {
		return nil, fmt.Errorf("invalid mask (type %T): %v", rawValue, rawValue)
	}
	maskCidr, err := netip.ParsePrefix(rawMask)
	if err != nil {
		return nil, fmt.Errorf("invalid mask: %s", rawMask)
	}

	var port int
	rawValue = rawMap["port"]
	if rawValue == nil {
		return nil, fmt.Errorf("missing port: %v", rawMap)
	}
	switch v := rawValue.(type) {
	case int:
		port = v

View on GitHub (pinned to dd8f660c0a)

Solutions

Add a `mask: <cidr>` key with a valid CIDR string to the entry
Check for key typos or case mismatches (`mask` must be lowercase and exact)
Ensure YAML doesn't parse the mask value as empty/null (provide a value after the colon)

Example fix

// before
- port: 4242
// after
- mask: 10.0.0.0/8
  port: 4242

Defensive patterns

Strategy: validation

Validate before calling

for _, e := range list {
	if m, ok := e.(map[string]any); ok {
		if _, present := m["mask"]; !present || m["mask"] == nil {
			return fmt.Errorf("entry missing mask: %v", m)
		}
	}
}

Type guard

func hasMask(e map[string]any) bool {
	v, ok := e["mask"]
	return ok && v != nil
}

Try / catch

if err != nil {
	if strings.Contains(err.Error(), "missing mask") {
		// message prints the whole offending entry map; locate and fix the entry
		return fmt.Errorf("add mask key to entry: %w", err)
	}
	return err
}

Prevention

Spell the key exactly `mask` (lowercase) — lookup is case-sensitive
Never leave `mask:` with an empty value in YAML
Validate required keys (mask, port) with a schema before deployment

When it happens

Trigger: A calculated_remotes entry map lacks the `mask` key entirely, or has `mask:` with no value (YAML null), causing rawValue == nil.

Common situations: Typos like `masks:` or `Mask:` (key lookup is exact and case-sensitive), deleted lines during config edits, or templates that skip optional fields.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

AI-assisted analysis of slackhq/nebula@dd8f660c0a (2026-09-03). Data as JSON: /api/errors/9450310e5fbad376. Report an issue: GitHub.