gohugoio/hugo · error

error processing file

Error message

error processing file %q

What it means

During front-matter conversion (hugo convert), convertAndSavePage constructs an errMsg for the file being processed (convert.go:148) and logs it via site.Log.Errorln when the file cannot be opened or its front matter cannot be parsed by pageparser. Open failures are logged and swallowed (returns nil so conversion continues); parse failures are logged and returned, stopping the conversion.

Solutions

1. Fix the malformed front matter in the indicated file
2. Verify the file's read permissions
3. Manually validate the front-matter syntax (e.g. with a TOML/YAML linter)
4. Run hugo convert on a clean checkout to rule out file corruption

Example fix

# before: broken front matter
+++
title = "My Post
date 2024-01-01
+++
# after: valid TOML
+++
title = "My Post"
date = 2024-01-01
+++

// Pre-validate front-matter syntax before running hugo convert.
func validateFrontMatter(path string) error {
    f, err := os.Open(path)
    if err != nil {
        return err
    }
    defer f.Close()
    _, err = pageparser.ParseFrontMatterAndContent(f)
    return err
}

// hugo convert logs and continues on open errors; handle the returned parse error.
if err := cmd.convertContents(format); err != nil {
    if strings.Contains(err.Error(), "error processing file") {
        log.Printf("some files had parse errors; check output")
    }
}

When it happens

Trigger: A content file with corrupted or unparseable front matter, or a file that cannot be read (permissions, encoding issues) during hugo convert toJSON/toTOML/toYAML.

Common situations: Malformed front-matter delimiters; invalid TOML/YAML/JSON in front matter; permission issues reading the file; binary or encoding problems.

Related errors

• failed to copy to
• failed to resolve output path
• failed to save file
• no existing content directory configured for this project
• aborted

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

Appendix: 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 52c9bd7908)