gohugoio/hugo · error

failed to convert metadata for file

Error message

failed to convert metadata for file %q: %s

What it means

After parsing, the importer calls `convertJekyllMetaData` to translate Jekyll front matter (permalink, category, layout, date) into Hugo conventions. This wraps a failure in that conversion step; `%q` is the filename, `%s` the underlying error (typically from `hmaps.ToStringMapE`).

Solutions

1. Inspect the named file's front matter and ensure it is a YAML/TOML object (map).
2. Flatten nested or array-shaped front matter values before importing.
3. Manually fix the offending metadata and re-run the import for that file.
4. Pre-process the Jekyll export to normalize front matter types.

Example fix

// before
---
permalink:
  en: /post/hello/
---
// after
---
url: /post/hello/
---

// Ensure front matter root is a mapping before importing.
func frontMatterIsMap(b []byte) bool {
  pf, err := pageparser.ParseFrontMatterAndContent(bytes.NewReader(b))
  if err != nil { return false }
  _, ok := pf.FrontMatter.(map[string]any)
  return ok
}

null

// Treat metadata conversion as best-effort and continue.
if _, err := convertJekyllMetaData(...); err != nil {
  log.Printf("metadata convert failed for %s: %v", filename, err)
  // fall back to writing metadata as-is or skip
}

When it happens

Trigger: Fires when front matter cannot be coerced into a `map[string]any` (e.g. it parsed as a scalar or array), or a field-level transformation encounters an unexpected type such as a non-string `permalink`/`category` that still fails the type assertion path.

Common situations: A Jekyll post whose front matter root is a list or bare string instead of an object; a `permalink`/`category` value that is a nested structure rather than a scalar; front matter produced by a plugin with non-standard schema.

Related errors

• failed to parse 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/8618a6ee103fb979. Report an issue: GitHub.

Appendix: source

Thrown at commands/import.go:327

	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
}

func (c *importCommand) copyJekyllFilesAndFolders(jekyllRoot, dest string, jekyllPostDirs map[string]bool) (err error) {
	fs := hugofs.Os

	fi, err := fs.Stat(jekyllRoot)

View on GitHub (pinned to 52c9bd7908)