What causes "failed to resolve output path %q: %w" in gohugoio/hugo?

`cd` into a directory that actually exists (e.g. the site root) and re-run the command.

failed to resolve output path %q: %w

Error message

failed to resolve output path %q: %w

What it means

Returned by `hugo convert` with --output when `filepath.Abs(c.outputDir)` fails while preparing to copy content directories (commands/convert.go:222-224). filepath.Abs only fails when the process's current working directory cannot be determined (needed to absolutize a relative path), so this is a rare environment-level failure rather than a bad flag value.

Source

Thrown at commands/convert.go:224

	contentDirs := make(map[string]bool)
	for _, p := range pagesBackedByFile {
		filename := p.File().Filename()
		contentDir := strings.TrimSuffix(filename, p.File().Path())
		if contentDir == filename {
			continue
		}
		contentDirs[filepath.Clean(contentDir)] = true
	}

	var contentDirList []string
	for contentDir := range contentDirs {
		contentDirList = append(contentDirList, contentDir)
	}
	slices.Sort(contentDirList)

	outputDirAbs, err := filepath.Abs(c.outputDir)
	if err != nil {
		return fmt.Errorf("failed to resolve output path %q: %w", c.outputDir, err)
	}

	for _, contentDir := range contentDirList {
		outputContentDirAbs := filepath.Join(outputDirAbs, filepath.Base(contentDir))

		skipDirs := make(map[string]bool)
		relToOutputDir, err := filepath.Rel(contentDir, outputDirAbs)
		if err == nil && relToOutputDir != ".." && !strings.HasPrefix(relToOutputDir, ".."+string(filepath.Separator)) {
			skipDirs[filepath.Clean(outputDirAbs)] = true
		}
		relToOutputContentDir, err := filepath.Rel(contentDir, outputContentDirAbs)
		if err == nil && relToOutputContentDir != ".." && !strings.HasPrefix(relToOutputContentDir, ".."+string(filepath.Separator)) {
			skipDirs[filepath.Clean(outputContentDirAbs)] = true
		}

		var shouldCopy func(filename string) bool
		if len(skipDirs) > 0 {
			shouldCopy = func(filename string) bool {

View on GitHub ↗ (pinned to 8a468df065)

Solutions

`cd` into a directory that actually exists (e.g. the site root) and re-run the command.
Pass an absolute path to -o/--output so no cwd resolution is needed.
If in CI/containers, ensure the working directory is created before hugo runs and not removed by a parallel cleanup step.

Example fix

# before (cwd was deleted)
hugo convert toYAML -o converted
# after
cd /path/to/site && hugo convert toYAML -o /path/to/site/converted

Defensive patterns

Strategy: validation

Validate before calling

abs, err := filepath.Abs(outputDir)
if err != nil {
    return err
}
if err := os.MkdirAll(abs, 0o755); err != nil {
    return fmt.Errorf("cannot create output dir %q: %w", abs, err)
}

Try / catch

if err != nil && strings.Contains(err.Error(), "failed to resolve output path") {
    // re-run with an absolute, pre-created output directory
}

Prevention

Pass absolute paths for the output directory; never rely on the process working directory
Create the output directory before invoking conversion
Avoid symlinked or mount-crossing output paths that break path resolution

When it happens

Trigger: Running `hugo convert to* -o <relative-path>` from a working directory that has been deleted or unmounted after the shell started (os.Getwd fails), or from a directory the process no longer has permission to stat — e.g. a temp dir cleaned up by another process, or an NFS mount that went away.

Common situations: Shells left in directories that were deleted (`rm -rf` from another terminal, CI workspace cleanup); containers whose workdir was removed; network filesystems dropping mid-session.

Related errors

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