cloudflare/cloudflared · error

error starting traceroute: %w

Error message

error starting traceroute: %w

What it means

decodeNetworkOutputToFile calls command.Start() to launch traceroute after wiring the stdout pipe. If the process cannot be started — binary missing, not executable, fork/exec failure — this wrapped error is returned and no hops are collected. It is the standard os/exec Start failure surfaced through the diagnostic network collector.

Source

Thrown at diagnostic/network/collector_utils.go:20

import (
	"bufio"
	"bytes"
	"fmt"
	"io"
	"os/exec"
)

type DecodeLineFunc func(text string) (*Hop, error)

func decodeNetworkOutputToFile(command *exec.Cmd, decodeLine DecodeLineFunc) ([]*Hop, string, error) {
	stdout, err := command.StdoutPipe()
	if err != nil {
		return nil, "", fmt.Errorf("error piping traceroute's output: %w", err)
	}

	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 {

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Verify traceroute is installed: which traceroute; install it (apt-get install traceroute / apk add traceroute).
2. Check the PATH used by the process running cloudflared and add the traceroute location.
3. Confirm the binary is executable and permitted by the security policy (seccomp/AppArmor/SELinux).
4. Run the diagnostic manually with the same user to reproduce and see the underlying exec error.

Example fix

// before
# container: trace fails
FROM alpine
// after
FROM alpine
RUN apk add --no-cache traceroute

if _, err := exec.LookPath("traceroute"); err != nil {
	return fmt.Errorf("traceroute not installed: %w", err)
}

hops, _, err := network.Collect(ctx, cfg)
var ee *exec.Error
if errors.As(err, &ee) && errors.Is(ee.Err, exec.ErrNotFound) {
	// install traceroute or fix PATH before retrying
}

When it happens

Trigger: network Collect invoked on a host where the traceroute binary does not exist in PATH, lacks the execute bit, or where fork/exec fails (resource limits, security policy blocking exec).

Common situations: Minimal container images without traceroute installed; PATH stripped in systemd services; AppArmor/seccomp policies blocking exec; missing CAP_NET_RAW for raw-socket traceroute modes (may fail at start depending on the mode).

Related errors

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

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