github/spec-kit · error · IntegrationDescriptorError

Command entry missing 'name' or 'file'

Error message

Command entry missing 'name' or 'file'

What it means

Raised by IntegrationDescriptor._validate() (src/specify_cli/integrations/catalog.py:790) when a provides.commands entry (a mapping) is missing the required 'name' or 'file' key. These two keys are the minimum contract for a command entry; later code reads cmd["name"] and cmd["file"] directly, so absence is fatal.

Source

Thrown at src/specify_cli/integrations/catalog.py:790

        if "commands" in provides and not isinstance(commands, list):
            raise IntegrationDescriptorError(
                "Invalid provides.commands: expected a list"
            )
        if "scripts" in provides and not isinstance(scripts, list):
            raise IntegrationDescriptorError(
                "Invalid provides.scripts: expected a list"
            )
        if not commands and not scripts:
            raise IntegrationDescriptorError(
                "Integration must provide at least one command or script"
            )
        for cmd in commands:
            if not isinstance(cmd, dict):
                raise IntegrationDescriptorError(
                    "Each command entry must be a mapping"
                )
            if "name" not in cmd or "file" not in cmd:
                raise IntegrationDescriptorError(
                    "Command entry missing 'name' or 'file'"
                )
            cmd_name = cmd["name"]
            cmd_file = cmd["file"]
            if not isinstance(cmd_name, str) or not cmd_name.strip():
                raise IntegrationDescriptorError(
                    "Command entry 'name' must be a non-empty string"
                )
            if not isinstance(cmd_file, str) or not cmd_file.strip():
                raise IntegrationDescriptorError(
                    "Command entry 'file' must be a non-empty string"
                )
            if os.path.isabs(cmd_file) or ".." in Path(cmd_file).parts or Path(cmd_file).drive or Path(cmd_file).anchor:
                raise IntegrationDescriptorError(
                    f"Command entry 'file' must be a relative path without '..': {cmd_file}"
                )
        for script_entry in scripts:
            if not isinstance(script_entry, str) or not script_entry.strip():

View on GitHub (pinned to bf88c9f9a8)

Solutions

1. Add the missing 'name' and/or 'file' key to each command entry flagged by validation.
2. Check spelling of keys — only 'name' and 'file' are required; extra keys are ignored but cannot substitute.
3. Reload the descriptor to confirm.

Example fix

# before
provides:
  commands:
    - name: plan

# after
provides:
  commands:
    - name: plan
      file: commands/plan.md

def missing_keys(commands):
    return [i for i, c in enumerate(commands)
            if not (isinstance(c, dict) and "name" in c and "file" in c)]

def is_complete_command(entry) -> bool:
    return (
        isinstance(entry, dict)
        and isinstance(entry.get("name"), str)
        and isinstance(entry.get("file"), str)
    )

When it happens

Trigger: A command mapping like '- name: plan' (no 'file') or '- file: commands/plan.md' (no 'name') inside provides.commands; the membership check 'name' not in cmd or 'file' not in cmd triggers the error.

Common situations: Typos in key names (e.g. 'filename:' instead of 'file:'); partial copy-paste of an existing entry; extra keys present but one required key forgotten.

Related errors

• Invalid provides.commands: expected a list
• Invalid provides.scripts: expected a list
• Integration must provide at least one command or script
• Each command entry must be a mapping
• Command entry 'name' must be a non-empty string

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