golang/go · error

failed to create trace reader: %w

Error message

failed to create trace reader: %w

What it means

`parseTrace` constructs a trace reader via `trace.NewReader`. If the header of the trace file is unreadable, indicates an unsupported/unknown trace version, or the file is empty/truncated below the header size, `NewReader` returns an error that is wrapped here. This happens before any event is read — the file never even made it to the parser.

Source

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

		pct := float64(progress) / float64(size) * 100
		log.Printf("%s of %s (%.1f%%) processed...", byteCount(progress), byteCount(size), pct)
	}
	return
}

type parsedTrace struct {
	events      []trace.Event
	summary     *trace.Summary
	size, valid int64
	err         error
}

func parseTrace(rr io.Reader, size int64) (*parsedTrace, error) {
	// Set up the reader.
	cr := countingReader{r: rr}
	r, err := trace.NewReader(&cr)
	if err != nil {
		return nil, fmt.Errorf("failed to create trace reader: %w", err)
	}

	// Set up state.
	s := trace.NewSummarizer()
	t := new(parsedTrace)
	var validBytes int64
	var validEvents int
	for {
		ev, err := r.ReadEvent()
		if err == io.EOF {
			validBytes = cr.bytesRead.Load()
			validEvents = len(t.events)
			break
		}
		if err != nil {
			t.err = err
			break
		}

View on GitHub (pinned to b6b368adc5)

Solutions

1. Confirm the file is a Go execution trace: it should start with `gotr` followed by a NUL byte (the trace magic) — `head -c 5 <file> | xxd`.
2. Re-record the trace with the same or older Go toolchain than the one opening it.
3. Make sure you invoked `runtime.StartTrace`/`runtime/trace.Start` and stopped cleanly; an unclean stop can truncate the header on some platforms.
4. Use `go tool trace -d=wire <file>` to inspect raw framing once the header is valid.

Example fix

// before
$ go tool trace heap.prof   # wrong file type
// after
$ go tool trace trace.out

// quick magic check before invoking go tool trace
hdr := make([]byte, 5)
if _, err := f.ReadAt(hdr, 0); err == nil && string(hdr) == "gotr\x00" {
    // looks like a Go trace
}

When it happens

Trigger: Feeding `go tool trace` a non-trace file (a random binary, a pprof heap profile, a core dump); a trace captured with a much newer Go version whose header the running toolchain doesn't recognize; a zero-byte or truncated-at-header trace; bytes captured without `runtime.Trace` framing.

Common situations: Passing a `.pprof` CPU profile by mistake; trace recorded on Go 1.2x and opened on Go 1.1x; SCP/rsync transfer that truncated; mixing up `go tool trace` and `go tool pprof` arguments.

Related errors

• failed to generate pprof: %v
• failed to parse any useful part of the trace: %v
• no trace file supplied
• gzip.ErrHeader
• zlib.ErrHeader

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