squidfunk/mkdocs-material · error · ValidationError

Expected 'created' date when using dictionary syntax

Error message

Expected 'created' date when using dictionary syntax

What it means

When the `date` metadata is given as a dictionary (rather than a single date), the schema requires a `created` key, which the plugin uses for sorting and display. If the DateDict has no `created` entry, `run_validation` raises this ValidationError.

Source

Thrown at src/plugins/blog/structure/options.py:99

            # only supplied a date, and convert it to datetime in UTC
            if isinstance(value, date):
                config[key_name][key] = datetime.combine(value, time()).replace(tzinfo=timezone.utc)

        # Initialize date dictionary
        config[key_name] = DateDict(config[key_name])

    # Ensure each date value is of type datetime
    def run_validation(self, value: DateDict):
        for key in value:
            if not isinstance(value[key], datetime):
                raise ValidationError(
                    f"Expected type: {date} or {datetime} "
                    f"but received: {type(value[key])}"
                )

        # Ensure presence of `date.created`
        if not value.created:
            raise ValidationError(
                "Expected 'created' date when using dictionary syntax"
            )

        # Return date dictionary
        return value

# -----------------------------------------------------------------------------

# Post links option
class PostLinks(BaseConfigOption[Navigation]):

    # Create navigation from structured items - we don't need to provide a
    # configuration object to the function, because it will not be used
    def run_validation(self, value: object):
        items = _data_to_navigation(value, Files([]), None)
        _add_parent_links(items)

        # Return navigation

View on GitHub (pinned to e2136532f4)

Solutions

  1. Add a `created` key to the date dictionary: `date: {created: 2024-01-15, updated: 2024-02-01}`
  2. Or replace the dictionary with a single date value `date: 2024-01-15`, which is treated as the creation date

Example fix

# before
---
date:
  updated: 2024-02-01
---

// after
---
date:
  created: 2024-01-15
  updated: 2024-02-01
---
Defensive patterns

Strategy: validation

Validate before calling

import yaml
for p in Path('docs/posts').rglob('*.md'):
    meta = yaml.safe_load(p.read_text().split('---')[1])
    d = meta.get('date')
    if isinstance(d, dict):
        assert 'created' in d, f"{p}: dictionary date syntax requires 'created'"

Type guard

def has_created_date(date_value):
    return not isinstance(date_value, dict) or 'created' in date_value

Try / catch

try:
    mkdocs.commands.build(config)
except ValidationError as e:
    if "Expected 'created' date" in str(e):
        log.error("Add 'created' to the date dictionary in the post")
    raise

Prevention

When it happens

Trigger: A post defines `date` as a mapping containing only keys like `updated` or `release`, without `created`, e.g. `date: {updated: 2024-02-01}`.

Common situations: Authors adding an `updated` date assuming it can stand alone; copying partial front-matter examples; migrating posts that previously used only an `updated` field.

Understand the failure class

Background: "Missing required field" and "field is required" errors: why libraries reject payloads that omit mandatory fields — this error's family across 20 libraries.

Related errors

AI-assisted analysis of squidfunk/mkdocs-material@e2136532f4 (2026-08-29). Data as JSON: /api/errors/dfbdb1ce080326bf. Report an issue: GitHub.