gohugoio/hugo · error

failed to parse file

Error message

failed to parse file %q: %s

What it means

During `hugo import jekyll`, each Jekyll post is read and parsed with `pageparser.ParseFrontMatterAndContent`. This wraps a failure to parse the front matter + body of a Jekyll Markdown file. The `%q` is the source filename; `%s` is the parser's underlying error.

Solutions

1. Open the named file and verify the front matter block is properly delimited with `---`.
2. Lint the YAML/TOML front matter with an external tool (`yamllint`).
3. Skip or fix the offending post and re-run the import.
4. Ensure the import targets text Markdown files, not binary uploads.

Example fix

// before
---
title: Hello
tags: [a, b
---
body
// after
---
title: Hello
tags: [a, b]
---
body

// Validate a Jekyll post's front matter delimiters before importing.
func validFrontMatter(b []byte) error {
  s := string(b)
  if !strings.HasPrefix(s, "---\n") { return fmt.Errorf("missing leading ---") }
  if strings.Count(s, "\n---\n") < 1 { return fmt.Errorf("missing closing ---") }
  return nil
}

null

// Per-file isolation: import Jekyll posts one at a time so a parse
// failure is reported without aborting the whole import.
for _, post := range posts {
  if err := convertJekyllPost(post, ...); err != nil {
    log.Printf("skip %s: %v", post, err); continue
  }
}

When it happens

Trigger: Fires inside `convertJekyllPost` when the Jekyll file's front matter delimiters are malformed (e.g. missing trailing `---`), the YAML/TOML is invalid, or the file is not a recognized front-matter format.

Common situations: A Jekyll post with a missing closing `---` after YAML front matter; mixed tab/space indentation that breaks YAML; a post exported from another CMS with non-standard front matter; an empty or binary file picked up by the import glob.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• failed to convert metadata for file
• abort: jekyll root contains neither posts nor drafts
• failed to convert content for file
• filename not match
• is not a directory

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

Appendix: source

Thrown at commands/import.go:323

	if err != nil {
		c.r.Printf("Failed to parse filename '%s': %s. Skipping.", filename, err)
		return nil
	}

	log.Println(filename, postDate, postName)

	targetFile := filepath.Join(targetDir, relPath)
	targetParentDir := filepath.Dir(targetFile)
	os.MkdirAll(targetParentDir, 0o777)

	contentBytes, err := os.ReadFile(path)
	if err != nil {
		c.r.logger.Errorln("Read file error:", path)
		return err
	}
	pf, err := pageparser.ParseFrontMatterAndContent(bytes.NewReader(contentBytes))
	if err != nil {
		return fmt.Errorf("failed to parse file %q: %s", filename, err)
	}
	newmetadata, err := c.convertJekyllMetaData(pf.FrontMatter, postName, postDate, draft)
	if err != nil {
		return fmt.Errorf("failed to convert metadata for file %q: %s", filename, err)
	}

	content, err := c.convertJekyllContent(newmetadata, string(pf.Content))
	if err != nil {
		return fmt.Errorf("failed to convert content for file %q: %s", filename, err)
	}

	fs := hugofs.Os
	if err := helpers.WriteToDisk(targetFile, strings.NewReader(content), fs); err != nil {
		return fmt.Errorf("failed to save file %q: %s", filename, err)
	}
	return nil
}

View on GitHub (pinned to 52c9bd7908)