What causes "Group ID %d is not between ping group %d to %d" in cloudflare/cloudflared?

Group ID %d is not between ping group %d to %d

Error message

Group ID %d is not between ping group %d to %d

What it means

On Linux, cloudflared's ICMP proxy needs to create raw ICMP sockets without root by writing to /proc/sys/net/ipv4/ping_group_range. checkInPingGroup parses the allowed min/max group IDs from that file and rejects the process's group if it falls outside the range. The error means the current group ID is not permitted to open unprivileged ping sockets.

Source

Thrown at ingress/icmp_linux.go:92

func checkInPingGroup() error {
	file, err := os.ReadFile(pingGroupPath)
	if err != nil {
		return err
	}
	groupID := uint64(os.Getegid())
	// Example content: 999	   59999
	found := findGroupIDRegex.FindAll(file, 2)
	if len(found) == 2 {
		groupMin, err := strconv.ParseUint(string(found[0]), 10, 32)
		if err != nil {
			return errors.Wrapf(err, "failed to determine minimum ping group ID")
		}
		groupMax, err := strconv.ParseUint(string(found[1]), 10, 32)
		if err != nil {
			return errors.Wrapf(err, "failed to determine maximum ping group ID")
		}
		if groupID < groupMin || groupID > groupMax {
			return fmt.Errorf("Group ID %d is not between ping group %d to %d", groupID, groupMin, groupMax)
		}
		return nil
	}
	return fmt.Errorf("did not find group range in %s", pingGroupPath)
}

func (ip *icmpProxy) Request(ctx context.Context, pk *packet.ICMP, responder ICMPResponder) error {
	ctx, span := responder.RequestSpan(ctx, pk)
	defer responder.ExportSpan()

	originalEcho, err := getICMPEcho(pk.Message)
	if err != nil {
		tracing.EndWithErrorStatus(span, err)
		return err
	}
	observeICMPRequest(ip.logger, span, pk.Src.String(), pk.Dst.String(), originalEcho.ID, originalEcho.Seq)

	shouldReplaceFunnelFunc := createShouldReplaceFunnelFunc(ip.logger, responder, pk, originalEcho.ID)

View on GitHub (pinned to 2253eeeb25)

Solutions

Widen the allowed range: `sudo sysctl -w net.ipv4.ping_group_range="0 2147483647"` and persist it in /etc/sysctl.d/.
Check the current range with `cat /proc/sys/net/ipv4/ping_group_range` and run cloudflared under a group inside that range.
Alternatively run cloudflared as root (or with CAP_NET_RAW) so the group check is bypassed.
Verify the group of the running user with `id -g` and add the user to a permitted group if the range is intentionally narrow.

Example fix

// before
$ cat /proc/sys/net/ipv4/ping_group_range
1	0        # disabled -> Group ID 1000 is not between ping group 1 to 0
// after
$ sudo sysctl -w net.ipv4.ping_group_range="0 2147483647"
$ cat /proc/sys/net/ipv4/ping_group_range
0	2147483647

Defensive patterns

Strategy: validation

Validate before calling

function canPingUnprivileged(): boolean {
  const range = fs.readFileSync('/proc/sys/net/ipv4/ping_group_range', 'utf8').trim().split(/\s+/).map(Number);
  const gid = process.getgid();
  return range.length === 2 && gid >= range[0] && gid <= range[1];
}

Type guard

func pingGroupInRange(groupID uint32) (bool, error) {
    data, err := os.ReadFile(pingGroupPath)
    if err != nil { return false, err }
    fields := strings.Fields(string(data))
    if len(fields) != 2 { return false, fmt.Errorf("unexpected ping_group_range: %q", data) }
    min, _ := strconv.ParseUint(fields[0], 10, 32)
    max, _ := strconv.ParseUint(fields[1], 10, 32)
    return groupID >= uint32(min) && groupID <= uint32(max), nil
}

Prevention

Set net.ipv4.ping_group_range='0 2147483647' in sysctl config on hosts running cloudflared as non-root.
Verify the running user's GID is inside ping_group_range before starting ICMP proxying.
In containers, pass the sysctl at launch (docker run --sysctl ...).
Prefer running with CAP_NET_RAW if group configuration is not possible.

When it happens

Trigger: testPermission -> checkInPingGroup runs when cloudflared starts the Linux ICMP proxy; it fails when /proc/sys/net/ipv4/ping_group_range has a range (e.g. '1 0' default meaning disabled, or a narrow range) that does not contain the process's groupID.

Common situations: Default kernel settings where ping_group_range is '1 0' (disabled); running cloudflared as a non-root user whose group is outside the configured range; hardened/containerized environments with restricted ping_group_range.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

AI-assisted analysis of cloudflare/cloudflared@2253eeeb25 (2026-09-06). Data as JSON: /api/errors/6c58ac54e9bd3fb1. Report an issue: GitHub.