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

Create the parent directory of the --profile-trace path or choose a writable location like ./trace.out.

failed to create trace file: %w

Error message

failed to create trace file: %w

What it means

Returned by initTraceProfile when os.Create fails for the path given via the --profile-trace flag (c.r.traceprofile). Hugo wraps the OS error so the user can see why the runtime trace output file could not be created.

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 8a468df065)

Solutions

Create the parent directory of the --profile-trace path or choose a writable location like ./trace.out.
Check write permissions and read-only mounts.
Avoid pointing the flag at an existing directory.

Example fix

// before
hugo --profile-trace /var/trace/out.trace
// after
hugo --profile-trace ./trace.out

Defensive patterns

Strategy: validation

Validate before calling

// verify trace output path before enabling --trace
dir := filepath.Dir(tracePath)
if fi, err := os.Stat(dir); err != nil || !fi.IsDir() {
    return fmt.Errorf("trace output dir invalid: %v", err)
}

Type guard

var pathErr *os.PathError
if errors.As(err, &pathErr) {
    // path creation failed
}

Try / catch

if err := b.build(); err != nil {
    var pe *os.PathError
    if errors.As(err, &pe) && strings.Contains(err.Error(), "trace file") {
        // retry without tracing
    }
    return err
}

Prevention

Pass an absolute path in a writable directory to the trace flag
Pre-create the output directory
Disable tracing in sandboxed or read-only filesystems

When it happens

Trigger: Running hugo with --profile-trace <path> where os.Create fails: missing parent directory, permission denied, path is a directory, or read-only filesystem.

Common situations: Trace path pointing into a directory that doesn't exist, CI/container read-only filesystems, or insufficient permissions on the target directory.

Related errors

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/b6617a7d5b1b8d8f.json. Report an issue: GitHub ↗.