github/spec-kit · error · ValidationError

Invalid provides.scripts: expected a list

Error message

Invalid provides.scripts: expected a list

What it means

If provides contains a scripts key, its value must be a list. Scripts are executable helpers the extension declares; the container-type check mirrors the commands and templates checks.

Source

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

        # 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

1. Use the list form: `scripts:\n - scripts/bash/helper.sh`.
2. Wrap each declared script in its own list entry.
3. Check a bundled extension that ships scripts for the canonical shape.

Example fix

# before
provides:
  scripts: scripts/bash/setup.sh

# after
provides:
  scripts:
    - scripts/bash/setup.sh

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

When it happens

Trigger: `provides:\n scripts:` set to a string, mapping, or single unwrapped entry. isinstance(scripts, list) fails.

Common situations: Same single-item dash omission as commands, or pointing scripts at a directory string rather than a list of script entries.

Related errors

• Invalid requires: expected a mapping, got {type(requires).__
• Invalid provides: expected a mapping, got {type(provides).__
• Invalid provides.commands: expected a list
• Invalid provides.templates: expected a list
• Invalid hooks: expected a mapping

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