What causes "failed to save file %q:: %w" in gohugoio/hugo?

Ensure the output directory exists and is writable (mkdir -p and chmod)

failed to save file

Error message

failed to save file %q:: %w

What it means

After converting front matter, convertAndSavePage writes the result with helpers.WriteToDisk (convert.go:198-199). If the write fails the error is wrapped with the target filename. Note the message contains a doubled colon ('::') typo.

Solutions

Ensure the output directory exists and is writable (mkdir -p and chmod)
Provide a valid writable --output path
Check available disk space
Run with appropriate user permissions for the output location

Example fix

# before
hugo convert toYAML --output /opt/readonly/out
# after
mkdir -p ~/converted && hugo convert toYAML --output ~/converted

Defensive patterns

Strategy: validation

Validate before calling

// Verify the output directory is writable before running hugo convert.
func ensureOutputWritable(dir string) error {
    if err := os.MkdirAll(dir, 0o755); err != nil {
        return err
    }
    probe := filepath.Join(dir, ".write_test")
    return os.WriteFile(probe, []byte("x"), 0o644)
}

Prevention

Create and chmod the --output directory before running hugo convert
Check disk space before large conversions
Use a fresh output directory to avoid permission conflicts

When it happens

Trigger: The output directory does not exist or is not writable, the disk is full, the path is too long, or a parent directory is missing.

Common situations: Using --output with a directory that lacks write permission; output on a read-only filesystem; disk full; path exceeds OS limits.

Related errors

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

Appendix: source

Thrown at commands/convert.go:199

	if err != nil {
		site.Log.Errorln(errMsg)
		return err
	}

	newContent.Write(pf.Content)

	newFilename := p.File().Filename()

	if c.outputDir != "" {
		contentDir := strings.TrimSuffix(newFilename, p.File().Path())
		contentDir = filepath.Base(contentDir)

		newFilename = filepath.Join(c.outputDir, contentDir, p.File().Path())
	}

	fs := hugofs.Os
	if err := helpers.WriteToDisk(newFilename, &newContent, fs); err != nil {
		return fmt.Errorf("failed to save file %q:: %w", newFilename, err)
	}

	return nil
}

func (c *convertCommand) copyContentDirsForOutput(pagesBackedByFile page.Pages) error {
	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 {

View on GitHub (pinned to 52c9bd7908)