What causes "Invalid provides.templates: expected a list" in github/spec-kit?

Use the list form: `templates:\n - path/to/template.md`.

github/spec-kit · error · ValidationError

Invalid provides.templates: expected a list

Error message

Invalid provides.templates: expected a list

What it means

If provides contains a templates key, its value must be a list. Templates are declared (not inline) artifacts the extension ships; the validator only checks the container type here, with per-artifact validation done by _validate_provided_artifacts afterwards.

Source

Thrown at src/specify_cli/extensions/__init__.py:386

                f"got {type(requires['speckit_version']).__name__}"
            )

        # Validate provides section
        provides = self.data["provides"]
        if not isinstance(provides, dict):
            raise ValidationError(
                f"Invalid provides: expected a mapping, got {type(provides).__name__}"
            )
        commands = provides.get("commands", [])
        templates = provides.get("templates", [])
        scripts = provides.get("scripts", [])
        hooks = self.data.get("hooks")
        events = self.data.get("events")

        if "commands" in provides and not isinstance(commands, list):
            raise ValidationError("Invalid provides.commands: expected a list")
        if "templates" in provides and not isinstance(templates, list):
            raise ValidationError("Invalid provides.templates: expected a list")
        if "scripts" in provides and not isinstance(scripts, list):
            raise ValidationError("Invalid provides.scripts: expected a list")
        if "hooks" in self.data and not isinstance(hooks, dict):
            raise ValidationError("Invalid hooks: expected a mapping")
        if "events" in self.data:
            from ..events import validate_events
            validate_events(self.data)

        has_commands = bool(commands)
        has_hooks = bool(hooks)
        has_events = bool(events)
        has_templates = bool(templates)
        has_scripts = bool(scripts)

        if not has_commands and not has_hooks and not has_events and not has_templates and not has_scripts:
            raise ValidationError(
                "Extension must provide at least one command, hook, or event "
                "(or a declared template/script)"

View on GitHub (pinned to bf88c9f9a8)

Solutions

Use the list form: `templates:\n - path/to/template.md`.
Keep each template entry consistent with what _validate_provided_artifacts expects (a mapping/string per entry).
Model on an existing extension that ships templates.

Example fix

# before
provides:
  templates: templates/plan.md

# after
provides:
  templates:
    - templates/plan.md

Defensive patterns

Strategy: validation

Validate before calling

def templates_list_ok(data: dict) -> bool:
    provides = data.get("provides", {})
    return "templates" not in provides or isinstance(provides["templates"], list)

Prevention

templates is a list, not a single path string.
Mirror the commands structure for symmetry and fewer mistakes.

When it happens

Trigger: `provides:\n templates:` set to a single string path or a single mapping instead of a list of entries. The isinstance(templates, list) check fails.

Common situations: Author writes `templates: templates/plan.md` as a shortcut instead of the list form the manifest schema expects.

Related errors

AI-assisted analysis of github/spec-kit@bf88c9f9a8 (2026-08-14). Data as JSON: /api/errors/2d0e9192ff4d6377. Report an issue: GitHub.