netbirdio/netbird · error

at least one distribution group is required

Error message

at least one distribution group is required

What it means

The last check in Zone.Validate(): DistributionGroups must contain at least one group ID. Zones distribute resolved DNS to peers through distribution groups, so a zone with no groups has no consumers and is rejected. Group existence is validated elsewhere; here only non-emptiness is enforced.

Source

Thrown at management/internals/modules/zones/zone.go:81

		enabled = *req.Enabled
	}
	z.Enabled = enabled
}

func (z *Zone) Validate() error {
	if z.Name == "" {
		return errors.New("zone name is required")
	}
	if len(z.Name) > 255 {
		return errors.New("zone name exceeds maximum length of 255 characters")
	}

	if !domain.IsValidDomainNoWildcard(z.Domain) {
		return errors.New("invalid zone domain format")
	}

	if len(z.DistributionGroups) == 0 {
		return errors.New("at least one distribution group is required")
	}

	return nil
}

func (z *Zone) EventMeta() map[string]any {
	return map[string]any{"name": z.Name, "domain": z.Domain}
}

View on GitHub (pinned to 93e97f4bf1)

Solutions

1. Include at least one existing group ID in distribution_groups, e.g. ["grp-1"].
2. Create the distribution group first if none exists yet, then reference its ID.
3. If calling NewZone, pass a non-empty []string of group IDs.

Example fix

// before
{"name": "Corp", "domain": "corp.example.com", "distribution_groups": []}
// after
{"name": "Corp", "domain": "corp.example.com", "distribution_groups": ["grp-1"]}

if len(req.DistributionGroups) == 0 {
    return fmt.Errorf("at least one distribution group is required")
}

if err := zone.Validate(); err != nil {
    return respondBadRequest(err)
}

When it happens

Trigger: Zone create/update with distribution_groups omitted, set to [], or to [""]; constructing a Zone via NewZone with a nil or empty slice.

Common situations: Forgetting the field on first zone creation; passing group names instead of IDs and an empty ID list; clients treating the field as optional because the OpenAPI marks other fields optional.

Related errors

• record name is required
• invalid record name format
• record type is required
• invalid CNAME target format
• invalid record type, must be A, AAAA, or CNAME

AI-assisted analysis of netbirdio/netbird@93e97f4bf1 (2026-08-16). Data as JSON: /api/errors/8b11307bc3f9bde8. Report an issue: GitHub.