squidfunk/mkdocs-material · error · ValidationError

Expected type: {date} or {datetime} but received: {type(valu

Error message

Expected type: {date} or {datetime} but received: {type(value[key])}

What it means

The blog plugin's date option accepts either a single date/datetime or a dictionary of date keys (created, updated, etc.). `run_validation` iterates the DateDict and raises this ValidationError if any value is not a `datetime` instance.

Source

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

                # Set timezone to UTC if not set
                if value.tzinfo is None:
                    config[key_name][key] = value.replace(tzinfo=timezone.utc)
                continue;


            # Handle date - we set 00:00:00 as the default time, if the author
            # 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]):

View on GitHub (pinned to e2136532f4)

Solutions

  1. Use ISO 8601 date values in the date dictionary, e.g. `date: {created: 2024-01-15}`
  2. Unquote date strings so YAML parses them as dates
  3. Remove non-date keys from the date dictionary

Example fix

# before
---
date:
  created: '2024/01/15'
  updated: soon
---

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

Strategy: type-guard

Validate before calling

import yaml, datetime
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):
        for k, v in d.items():
            assert isinstance(v, (datetime.date, datetime.datetime)), f"{p}: date.{k} not a date"

Type guard

def all_dates_are_datetimes(date_dict):
    return all(isinstance(v, datetime) for v in date_dict.values())

Try / catch

try:
    mkdocs.commands.build(config)
except ValidationError as e:
    if "Expected type" in str(e):
        log.error(f"Use ISO dates in the date dictionary: {e}")
    raise

Prevention

When it happens

Trigger: In a post's front-matter, a key inside the date dictionary (e.g. `date: {created: 2024-01-15, updated: ...}`) is set to a string, int, or other non-date value, so after parsing it is not a `datetime`.

Common situations: Writing `date: {created: 'yesterday'}` or an unparseable/timestamp-as-string value; YAML keeping the value as a string because the format is not a recognized date; passing a plain string like `2024-01-15` in quotes where the loader doesn't coerce it.

Related errors

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