{"record":{"id":"e6d21e766bd10192","repo":"github/spec-kit","slug":"command-entry-file-must-be-a-non-empty-string","errorCode":null,"errorMessage":"Command entry 'file' must be a non-empty string","messagePattern":"Command entry 'file' must be a non-empty string","errorType":"validation","errorClass":"IntegrationDescriptorError","httpStatus":null,"severity":"error","filePath":"src/specify_cli/integrations/catalog.py","lineNumber":800,"sourceCode":"                \"Integration must provide at least one command or script\"\n            )\n        for cmd in commands:\n            if not isinstance(cmd, dict):\n                raise IntegrationDescriptorError(\n                    \"Each command entry must be a mapping\"\n                )\n            if \"name\" not in cmd or \"file\" not in cmd:\n                raise IntegrationDescriptorError(\n                    \"Command entry missing 'name' or 'file'\"\n                )\n            cmd_name = cmd[\"name\"]\n            cmd_file = cmd[\"file\"]\n            if not isinstance(cmd_name, str) or not cmd_name.strip():\n                raise IntegrationDescriptorError(\n                    \"Command entry 'name' must be a non-empty string\"\n                )\n            if not isinstance(cmd_file, str) or not cmd_file.strip():\n                raise IntegrationDescriptorError(\n                    \"Command entry 'file' must be a non-empty string\"\n                )\n            if os.path.isabs(cmd_file) or \"..\" in Path(cmd_file).parts or Path(cmd_file).drive or Path(cmd_file).anchor:\n                raise IntegrationDescriptorError(\n                    f\"Command entry 'file' must be a relative path without '..': {cmd_file}\"\n                )\n        for script_entry in scripts:\n            if not isinstance(script_entry, str) or not script_entry.strip():\n                raise IntegrationDescriptorError(\n                    \"Script entry must be a non-empty string\"\n                )\n            if os.path.isabs(script_entry) or \"..\" in Path(script_entry).parts or Path(script_entry).drive or Path(script_entry).anchor:\n                raise IntegrationDescriptorError(\n                    f\"Script entry must be a relative path without '..': {script_entry}\"\n                )\n\n    # -- Property accessors -----------------------------------------------\n","sourceCodeStart":782,"sourceCodeEnd":818,"githubUrl":"https://github.com/github/spec-kit/blob/bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c/src/specify_cli/integrations/catalog.py#L782-L818","documentation":"Raised by IntegrationDescriptor._validate() (src/specify_cli/integrations/catalog.py:800) when a provides.commands entry's 'file' value is not a string or is empty/whitespace-only. The file value points at the command template inside the integration package, so it must be a non-empty string before the path-safety check that follows.","triggerScenarios":"A command entry with 'file: null', 'file: \"\"', or a non-string YAML value; the isinstance/strip guard fails before the relative-path check at catalog.py:804 runs.","commonSituations":"Commenting out a file path but leaving the key with an empty value; YAML parsing 'file: commands/plan.md # note' with trailing syntax errors producing null; copy-paste that lost the value.","solutions":["Set 'file' to a non-empty relative path string such as 'commands/plan.md'.","Verify the key has a value and the YAML under it is not commented out or mis-indented.","Reload the descriptor to confirm validation passes."],"exampleFix":"# before\n- name: plan\n  file:\n\n# after\n- name: plan\n  file: commands/plan.md","handlingStrategy":"type-guard","validationCode":"def bad_files(commands):\n    return [c for c in commands\n            if not isinstance(c.get(\"file\"), str) or not c[\"file\"].strip()]","typeGuard":"def is_nonempty_file(v) -> bool:\n    return isinstance(v, str) and bool(v.strip()) and not v.startswith((\"/\", \"\\\\\"))","tryCatchPattern":null,"preventionTips":["Give 'file' a concrete relative path value.","Check that YAML under the key is not commented out or mis-indented.","Confirm the referenced template file actually exists in the package."],"tags":["yaml","validation","integration-descriptor","spec-kit"],"backgroundTag":null,"analyzedSha":"bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c","analyzedAt":"2026-08-14T19:43:37.150Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}