What causes "failed to create trace file: %w" in gohugoio/hugo?

Create and confirm write access to the parent directory, then re-run with an absolute `--trace` path.

failed to create trace file

Error message

failed to create trace file: %w

What it means

Hugo's `hugoBuilder.initTraceProfile` calls `os.Create(c.r.traceprofile)` to open the file for an execution tracer capture (set via `--trace`). This wraps the OS-level failure to create that file, before `trace.Start` is ever called.

Solutions

Create and confirm write access to the parent directory, then re-run with an absolute `--trace` path.
Switch to a writable temp directory such as `/tmp/hugo-trace.out`.
Drop `--trace` if you do not need the execution trace.

Example fix

// before
// $ hugo --trace=/opt/traces/trace.out   (dir absent)
// after
// $ mkdir -p /tmp/traces && hugo --trace=/tmp/traces/trace.out

Defensive patterns

Strategy: validation

Validate before calling

func validateTracePath(p string) error {
  dir := filepath.Dir(p)
  if _, err := os.Stat(dir); err != nil { return err }
  f, err := os.CreateTemp(dir, ".hugotrace-*")
  if err != nil { return err }
  f.Close(); os.Remove(f.Name())
  return nil
}

Type guard

null

Try / catch

null

Prevention

Use an absolute `--trace` path in a writable temp directory.
Confirm the parent directory exists before invoking Hugo.
Omit `--trace` unless you actively need an execution trace.

When it happens

Trigger: Fires when `c.r.traceprofile != ""` and `os.Create` fails — missing parent directory, unwritable location, or insufficient permissions on the target path.

Common situations: Passing `--trace` with a path whose directory doesn't exist; running Hugo in a container or CI where the cwd is read-only; a relative path resolved against an unexpected working directory.

Related errors

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

Appendix: source

Thrown at commands/hugobuilder.go:300

		if stopTraceProf != nil {
			stopTraceProf()
		}

		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 != ""

View on GitHub (pinned to 52c9bd7908)