golang/go · error

failed to read trace file: %w

Error message

failed to read trace file: %w

What it means

The `go tool trace` command failed to open the trace file specified on the command line. This is a standard OS-level file open error wrapped with context via `logAndDie`, which prints the error and exits. The trace file is a binary file produced by `runtime/trace` containing execution trace events from a Go program.

Source

Thrown at src/cmd/trace/main.go:98

	flag.Parse()
	counter.Inc("trace/invocations")
	counter.CountFlags("trace/flag:", *flag.CommandLine)

	// Go 1.7 traces embed symbol info and does not require the binary.
	// But we optionally accept binary as first arg for Go 1.5 traces.
	switch flag.NArg() {
	case 1:
		traceFile = flag.Arg(0)
	case 2:
		programBinary = flag.Arg(0)
		traceFile = flag.Arg(1)
	default:
		flag.Usage()
	}

	tracef, err := os.Open(traceFile)
	if err != nil {
		logAndDie(fmt.Errorf("failed to read trace file: %w", err))
	}
	defer tracef.Close()

	// Get the size of the trace file.
	fi, err := tracef.Stat()
	if err != nil {
		logAndDie(fmt.Errorf("failed to stat trace file: %v", err))
	}
	traceSize := fi.Size()

	// Handle requests for profiles.
	if *pprofFlag != "" {
		parsed, err := parseTrace(tracef, traceSize)
		if err != nil {
			logAndDie(err)
		}
		var f traceviewer.ProfileFunc
		switch *pprofFlag {

View on GitHub (pinned to b6b368adc5)

Solutions

1. Verify the trace file exists: `ls -la <trace_file>`.
2. Check file permissions: ensure read access.
3. If using relative paths, verify the working directory or switch to an absolute path.
4. Ensure the trace file was generated correctly: use `runtime/trace.Start(f)` and `runtime/trace.Stop()` in your program.
5. Verify you're passing the correct number of arguments: `go tool trace <trace_file>` or `go tool trace <binary> <trace_file>`.

Example fix

# Before: wrong path or missing file
go tool trace trace.out  # file doesn't exist

# After: generate trace file first, then verify path
# In Go program:
#   f, _ := os.Create("trace.out")
#   trace.Start(f)
#   ... run workload ...
#   trace.Stop()
#   f.Close()

ls -la trace.out
go tool trace trace.out

// Validate trace file exists before passing to go tool trace
traceFile := flag.Arg(0)
if info, err := os.Stat(traceFile); err != nil {
    log.Fatalf("Trace file not found: %s", traceFile)
} else if info.IsDir() {
    log.Fatalf("Trace path is a directory, not a file: %s", traceFile)
} else if info.Size() == 0 {
    log.Fatalf("Trace file is empty: %s", traceFile)
}

When it happens

Trigger: Fires at trace/main.go:96-98 when `os.Open(traceFile)` returns an error. The trace file path comes from command-line arguments (either the only argument or the second argument when a binary is also specified). The `logAndDie` function prints the error to stderr and calls `os.Exit(1)`.

Common situations: Typo in the trace file path. The trace file was deleted or never generated. Insufficient file permissions. Wrong working directory when using a relative path. The file path was accidentally given as the first of two args (interpreted as program binary, not trace file). Trying to open a directory instead of a file.

Related errors

• failed to stat trace file: %v
• unknown pprof type %s
• failed to generate pprof: %v
• tool %q is ambiguous; choose one of:
• no trace file supplied

AI-assisted analysis of golang/go@b6b368adc5 (2026-08-12). Data as JSON: /api/errors/45295f4480faa65b. Report an issue: GitHub.