gohugoio/hugo · error

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

Error message

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

What it means

Emitted by the front matter date handler in page_frontmatter.go when a field mapped to a date (date, publishDate/publishdate, lastmod, expiryDate, unpublishdate, or any key configured under `frontmatter`) holds a value that `htime.ToTimeInDefaultLocationE` cannot parse in the site's configured location. Hugo needs real `time.Time` values to sort, filter drafts/expired content, and render date formats, so an unparsable value fails the build. The message includes the offending key and the page path or title.

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

Solutions

1. Rewrite the value in the reported page as RFC 3339 / ISO 8601, e.g. `2026-07-31` or `2026-07-31T14:00:00-05:00`.
2. Read the `see <path>` portion of the message to find the exact page, then check every date-ish key on it, not just `date`.
3. If the field is a custom date wired through `[frontmatter]` in hugo.toml, confirm the source key actually contains a date and reorder the fallback list if it doesn't.
4. Verify `timeZone` in your site config is a valid IANA zone (e.g. `America/New_York`), since parsing happens in that location.
5. For bulk migrations, script a pass over content/ normalizing date strings before rebuilding.

Example fix

# before
---
date: 31/07/2026
---

# after
---
date: 2026-07-31
---

// validate the date string parses before writing front matter
if _, err := time.Parse(time.RFC3339, dateStr); err != nil {
    return fmt.Errorf("front matter date %q not RFC3339: %w", dateStr, err)
}

When it happens

Trigger: A page with `date: 2024-13-45`, `date: "last tuesday"`, an empty-but-non-null quoted value, or a numeric timestamp in an unrecognized form; also fires for custom date fields wired through the `[frontmatter]` config mapping (e.g. `lastmod: ["myCustomDate", "date"]`) whose source key holds a non-date.

Common situations: Locale-formatted dates such as `31/07/2026` or `07-31-2026` that aren't RFC 3339/ISO 8601; TOML dates accidentally quoted as strings with a trailing timezone abbreviation; content migrated from Jekyll/WordPress carrying formats Hugo doesn't accept; setting `timeZone` in config to an invalid IANA name so location-aware parsing misbehaves.

Related errors

• error processing file %q
• failed to create page from pageMetaSource %s: %w
• failed to parse file %q: %s
• failed to convert metadata for file %q: %s
• error building site: %w

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