gohugoio/hugo · error

failed to start trace

Error message

failed to start trace: %w

What it means

Once the trace file is created, Hugo calls `trace.Start(f)` from the `runtime/trace` package. This error wraps that failure, which the Go runtime produces when tracing is already in progress in the process. The trace file is not closed here (it is closed later in the stop func).

Solutions

1. Stop the other `trace.Start` session before invoking Hugo's `--trace` path.
2. Run Hugo as its own process so the tracer is not already active.
3. Do not pass `--trace` when tracing is managed externally.

Example fix

// before
trace.Start(f1) // host app still tracing
hugo.Build(...)  // Hugo then calls trace.Start(f2) -> error
// after
trace.Stop()    // end prior trace first
hugo.Build(...)

// In a host app, ensure only one execution tracer runs.
var traceActive bool
func safeStartTrace(f *os.File) error {
  if traceActive { return fmt.Errorf("trace already active") }
  if err := trace.Start(f); err != nil { return err }
  traceActive = true
  return nil
}

null

err := hugo.Build(cfg)
if err != nil && strings.Contains(err.Error(), "failed to start trace") {
  // stop the host's active tracer, or drop Hugo's --trace flag and retry
}

When it happens

Trigger: Occurs when `trace.Start` returns non-nil — almost always because `runtime/trace` is already started by another component in the same process.

Common situations: Embedding Hugo in a host application that already started execution tracing; a shared test fixture that calls `trace.Start`; concurrent invocations of the build pipeline within one binary.

Related errors

• failed to create trace file
• abort: jekyll root contains neither posts nor drafts
• arguments must be slices or arrays
• arguments to complement must be slices or arrays
• arguments to symdiff must be slices or arrays

AI-assisted analysis of gohugoio/hugo@52c9bd7908 (2026-08-09). Data as JSON: /api/errors/13d84285d9d7b975. Report an issue: GitHub.

Appendix: source

Thrown at commands/hugobuilder.go:304

		if stopMemTicker != nil {
			stopMemTicker()
		}
	}, nil
}

func (c *hugoBuilder) initTraceProfile() (func(), error) {
	if c.r.traceprofile == "" {
		return nil, nil
	}

	f, err := os.Create(c.r.traceprofile)
	if err != nil {
		return nil, fmt.Errorf("failed to create trace file: %w", err)
	}

	if err := trace.Start(f); err != nil {
		return nil, fmt.Errorf("failed to start trace: %w", err)
	}

	return func() {
		trace.Stop()
		f.Close()
	}, nil
}

// newWatcher creates a new watcher to watch filesystem events.
func (c *hugoBuilder) newWatcher(pollIntervalStr string, dirList ...string) (*watcher.Batcher, error) {
	staticSyncer := &staticSyncer{c: c}

	var pollInterval time.Duration
	poll := pollIntervalStr != ""
	if poll {
		pollInterval, err := types.ToDurationE(pollIntervalStr)
		if err != nil {
			return nil, fmt.Errorf("invalid value for flag poll: %s", err)

View on GitHub (pinned to 52c9bd7908)