What causes "failed to convert metadata for file %q: %s" in gohugoio/hugo?

Read the wrapped underlying error message after the filename to identify the offending front matter key.

failed to convert metadata for file %q: %s

Error message

failed to convert metadata for file %q: %s

What it means

Emitted by Hugo's `hugo import jekyll` command in `convertJekyllPost` when `convertJekyllMetaData` fails to transform a Jekyll post's front matter into Hugo-compatible metadata. Hugo parses each post's front matter and rewrites Jekyll-specific keys (layout, permalink, date, draft status) into Hugo front matter; if that transformation errors, the whole conversion of that file aborts with this wrapped error.

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 8a468df065)

Solutions

Read the wrapped underlying error message after the filename to identify the offending front matter key.
Open the named Jekyll post and fix or normalize the invalid front matter (especially date fields) so it is valid YAML with expected types.
Re-run the import; convert stubborn posts manually by copying content and writing Hugo front matter by hand.

Example fix

# before (post front matter)
---
date: 31/12/2015
---
# after
---
date: 2015-12-31
---

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-parse the front matter yourself before invoking import
if _, err := metadecoders.Default.UnmarshalToMap(frontMatter, metadecoders.YAML); err != nil {
    log.Printf("skipping %s: bad metadata: %v", path, err)
}

Try / catch

if err := convertJekyllPost(path); err != nil {
    if strings.Contains(err.Error(), "failed to convert metadata") {
        // log the file and continue with remaining posts
    }
    return err
}

Prevention

Lint Jekyll front matter (valid YAML, closed --- fences) before running hugo import
Normalize non-standard date/tag fields in the source posts first
Run the import on a copy so partial failures don't corrupt originals

When it happens

Trigger: Running `hugo import jekyll <jekyllRoot> <target>` on a post whose front matter parses but contains metadata that convertJekyllMetaData cannot convert — e.g. malformed or unexpected date values, non-map front matter structures, or values whose types don't match what the converter expects.

Common situations: Migrating an old Jekyll blog where posts have hand-edited or plugin-generated front matter; posts with unusual date formats in front matter overriding the filename date; YAML values with unexpected types (arrays where scalars are expected).

Related errors

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