cloudflare/cloudflared · error

error finishing traceroute: %w

Error message

error finishing traceroute: %w

What it means

After streaming traceroute output, decodeNetworkOutputToFile calls command.Wait() to reap the process. If traceroute exits with a non-zero status or Wait fails, this wrapped error is returned. A common cause is traceroute being unable to reach the target or lacking privileges, though note decoding errors are checked only after Wait succeeds.

Source

Thrown at diagnostic/network/collector_utils.go:35

	}

	if err := command.Start(); err != nil {
		return nil, "", fmt.Errorf("error starting traceroute: %w", err)
	}

	// Tee the output to a string to have the raw information
	// in case the decode call fails
	// This error is handled only after the Wait call below returns
	// otherwise the process can become a zombie
	buf := bytes.NewBuffer([]byte{})
	tee := io.TeeReader(stdout, buf)
	hops, err := Decode(tee, decodeLine)
	// regardless of success of the decoding
	// consume all output to have available in buf
	_, _ = io.ReadAll(tee)

	if werr := command.Wait(); werr != nil {
		return nil, "", fmt.Errorf("error finishing traceroute: %w", werr)
	}

	if err != nil {
		return nil, buf.String(), err
	}

	return hops, buf.String(), nil
}

func Decode(reader io.Reader, decodeLine DecodeLineFunc) ([]*Hop, error) {
	scanner := bufio.NewScanner(reader)
	scanner.Split(bufio.ScanLines)

	var hops []*Hop

	for scanner.Scan() {
		text := scanner.Text()
		if text == "" {

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Inspect the wrapped exit error (exec.ExitError) for traceroute's exit code and stderr.
2. Run traceroute manually with the same arguments and user to reproduce (e.g. permission denied sending probes).
3. Grant CAP_NET_RAW (setcap cap_net_raw+ep on the traceroute binary) or run in a privileged network context.
4. Retry collection; if the target is unreachable, treat as an environmental finding rather than a code bug.

Example fix

// before
# traceroute: icmp socket Permission denied
$ cloudflared diag ...
// after
$ sudo setcap cap_net_raw+ep $(which traceroute)
$ cloudflared diag ...

// pre-check traceroute privileges
if _, err := os.Stat("/proc/net/raw"); err != nil {
	// raw sockets may be unavailable
}
err := exec.Command("traceroute", "-n", "-m", "1", "127.0.0.1").Run()

hops, _, err := network.Collect(ctx, cfg)
var ee *exec.ExitError
if errors.As(err, &ee) {
	// traceroute exited non-zero: check ee.ExitCode and the tee'd raw output
}

When it happens

Trigger: The traceroute process terminates abnormally: exits non-zero (unreachable host with certain flags, ICMP permission failure, killed by signal), or Wait itself fails after the process already had its resources collected.

Common situations: traceroute run without CAP_NET_RAW/setuid in containers (permission denied sending probes); network unreachable for the target; traceroute killed by timeout/signal handling; duplicate Wait calls in modified code.

Related errors

• couldn't parse index from timeout hop: %w
• error piping traceroute's output: %w
• error starting traceroute: %w
• scanner reported an error: %w
• error waiting from command '%s': %w

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