github/spec-kit · error · IntegrationDescriptorError

Command entry 'name' must be a non-empty string

Error message

Command entry 'name' must be a non-empty string

What it means

Raised by IntegrationDescriptor._validate() (src/specify_cli/integrations/catalog.py:796) when a provides.commands entry's 'name' value is not a string or is empty/whitespace-only. Command names become file stems and identifiers downstream, so they must be non-empty strings.

Source

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

                "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():
                raise IntegrationDescriptorError(
                    "Script entry must be a non-empty string"
                )
            if os.path.isabs(script_entry) or ".." in Path(script_entry).parts or Path(script_entry).drive or Path(script_entry).anchor:
                raise IntegrationDescriptorError(
                    f"Script entry must be a relative path without '..': {script_entry}"

View on GitHub (pinned to bf88c9f9a8)

Solutions

1. Quote the name and give it a non-empty value: name: "plan".
2. Ensure the value is a string, not a YAML number/boolean/null.
3. Re-validate the descriptor.

Example fix

# before
- name: 0123
  file: commands/plan.md

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

def bad_names(commands):
    return [c for c in commands
            if not isinstance(c.get("name"), str) or not c["name"].strip()]

def is_nonempty_str(v) -> bool:
    return isinstance(v, str) and bool(v.strip())

When it happens

Trigger: A command entry with 'name: 123', 'name: null', 'name: ""', or 'name: " "'; the isinstance/strip check fails and IntegrationDescriptorError is raised.

Common situations: YAML unquoted values parsed as non-strings (numbers, booleans, null); deleting a name's text while leaving the key; using a numeric command id.

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 missing 'name' or 'file'

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