gohugoio/hugo · warning

the front matter field is not a parsable date: see

Error message

the %q front matter field is not a parsable date: see %s

What it means

Thrown (and logged, not fatal) by the date front matter handler when a configured date field (date, lastmod, publishdate, expirydate, or a custom date key) holds a value that htime.ToTimeInDefaultLocationE cannot parse. The chained handler logs it and continues to the next candidate, so the page still builds but that date stays unset.

Solutions

1. Use an ISO 8601 date/datetime in the flagged front matter field (YYYY-MM-DD or RFC3339).
2. Verify the field named in the error message matches an intended date key.
3. Configure [frontmatter] date keys/formats if you need a non-default date source or format.

Example fix

# before
---
date: 2024-13-99
---
# after
---
date: 2024-12-31T15:00:00Z
---

if _, err := htime.ToTimeInDefaultLocationE(fm[key], loc); err != nil {
    return fmt.Errorf("field %q is not a valid date", key)
}

// logged by the chained handler; no fatal stop.
// To surface it, grep the build log for 'not a parsable date'.

When it happens

Trigger: Front matter sets e.g. 'date: 2024-13-99' or 'date: not-a-date', or a value in a locale-specific format Hugo's date parser rejects (e.g. '31/12/2024' depending on config).

Common situations: Hand-editing front matter with malformed dates, copying dates from spreadsheets in DD/MM/YYYY, or switching date formats after migration. The error names the field and the page path so the offending file is easy to find.

Related errors

• failed to convert metadata for file
• failed to decode page map
• failed to decode sites from front matter
• failed to parse file
• failed to resolve media type for

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

Appendix: source

Thrown at resources/page/pagemeta/page_frontmatter.go:1034

		if found {
			d.PageConfigLate.Params[key] = v
		} else {
			// Reentry from previous handlers.
			v, found = d.PageConfigLate.Params[key]
		}

		if !found || v == "" || v == nil {
			return false, nil
		}

		var date time.Time
		if vt, ok := v.(time.Time); ok && vt.Location() == d.Location {
			date = vt
		} else {
			var err error
			date, err = htime.ToTimeInDefaultLocationE(v, d.Location)
			if err != nil {
				return false, fmt.Errorf("the %q front matter field is not a parsable date: see %s", key, d.PathOrTitle)
			}
			d.PageConfigLate.Params[key] = date
		}

		// We map several date keys to one, so, for example,
		// "expirydate", "unpublishdate" will all set .ExpiryDate (first found).
		setter(d, date)

		return true, nil
	}
}

func (f *frontmatterFieldHandlers) newDateFilenameHandler(setter func(d *FrontMatterDescriptor, t time.Time)) frontMatterFieldHandler {
	return func(d *FrontMatterDescriptor) (bool, error) {
		date, slug := dateAndSlugFromBaseFilename(d.Location, d.BaseFilename)
		if date.IsZero() {
			return false, nil
		}

View on GitHub (pinned to 52c9bd7908)