What causes "error processing file %q" in gohugoio/hugo?

Note the file path in the log line and open that file — verify its front matter block has matching opening/closing delimiters (`---` for YAML, `+++` for TOML, `{...}` for JSON) and valid syntax inside.

gohugoio/hugo · error

error processing file %q

Error message

error processing file %q

What it means

Logged (and sometimes returned) by `hugo convert` when a content file cannot be opened or its front matter parsed during format conversion (commands/convert.go:148-165). It is created once per page as a shared message, then emitted if `Meta().Open()` fails or `pageparser.ParseFrontMatterAndContent` cannot split the file into front matter and body.

Source

Thrown at commands/convert.go:148

	}
	c.h = h
	return nil
}

func (c *convertCommand) convertAndSavePage(p page.Page, site *hugolib.Site, targetFormat metadecoders.Format) error {
	// The resources are not in .Site.AllPages.
	for _, r := range p.Resources().ByType("page") {
		if err := c.convertAndSavePage(r.(page.Page), site, targetFormat); err != nil {
			return err
		}
	}

	if p.File() == nil {
		// No content file.
		return nil
	}

	errMsg := fmt.Errorf("error processing file %q", p.File().Path())

	site.Log.Infoln("attempting to convert", p.File().Filename())

	f := p.File()
	file, err := f.FileInfo().Meta().Open()
	if err != nil {
		site.Log.Errorln(errMsg)
		file.Close()
		return nil
	}

	pf, err := pageparser.ParseFrontMatterAndContent(file)
	if err != nil {
		site.Log.Errorln(errMsg)
		file.Close()
		return err
	}

View on GitHub ↗ (pinned to 8a468df065)

Solutions

Note the file path in the log line and open that file — verify its front matter block has matching opening/closing delimiters (`---` for YAML, `+++` for TOML, `{...}` for JSON) and valid syntax inside.
Validate the front matter with a standalone parser (e.g. paste the YAML into yamllint) and fix the reported syntax error.
Check the file is readable (permissions, not a broken symlink) and UTF-8 encoded.
Re-run the convert; only the offending file blocks — fix files one by one as reported.

Example fix

# before (content/post/a.md)
---
title: "My post
date: 2024-01-01
--
# after
---
title: "My post"
date: 2024-01-01
---

Defensive patterns

Strategy: try-catch

Validate before calling

info, err := os.Stat(path)
if err != nil || info.IsDir() {
    // skip: not a readable regular file
}

Try / catch

if err := convertFile(path); err != nil {
    log.Printf("skipping %q: %v", path, err)
    continue // process remaining files; report failures at the end
}

Prevention

Run conversion on a clean git tree so a partial failure is trivially revertable
Validate front matter parses before running bulk conversion (hugo --printPathWarnings, dry runs)
Collect per-file errors and report them in aggregate instead of aborting on the first

When it happens

Trigger: Running `hugo convert toTOML|toYAML|toJSON` over a content tree containing a file that (a) can't be opened from the filesystem (permissions, deleted mid-run, broken symlink), or (b) has malformed front matter — unclosed `---`/`+++` delimiters, invalid YAML/TOML/JSON inside the front matter block, or stray BOM/encoding issues that break the page parser.

Common situations: Content imported from another SSG with slightly different front-matter delimiters; a merge conflict marker (`<<<<<<<`) left inside front matter; files with Windows-1252/UTF-16 encoding; unreadable files owned by another user in Docker volumes.

Related errors

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