{"record":{"id":"387830dae2233ec7","repo":"github/spec-kit","slug":"archive-must-contain-workflow-yml-at-its-root-or-i","errorCode":null,"errorMessage":"Archive must contain workflow.yml at its root or in exactly one top-level directory","messagePattern":"Archive must contain workflow\\.yml at its root or in exactly one top-level directory","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/specify_cli/workflows/_commands.py","lineNumber":937,"sourceCode":"            \"[yellow]Warning:[/yellow] Workflow installed, but its backup file \"\n            f\"could not be cleaned up: {_escape_markup(str(exc))}. Remove it \"\n            f\"manually: {_escape_markup(str(backup_file))}\"\n        )\n\n\ndef _workflow_package_root(extracted_root: Path) -> Path:\n    \"\"\"Resolve a root-level or single-nested workflow package.\"\"\"\n    if (extracted_root / \"workflow.yml\").is_file():\n        return extracted_root\n    entries = list(extracted_root.iterdir())\n    if (\n        len(entries) == 1\n        and entries[0].is_dir()\n        and not entries[0].is_symlink()\n        and (entries[0] / \"workflow.yml\").is_file()\n    ):\n        return entries[0]\n    raise ValueError(\n        \"Archive must contain workflow.yml at its root or in exactly one \"\n        \"top-level directory\"\n    )\n\n\ndef _validate_local_workflow_package(package_dir: Path) -> None:\n    \"\"\"Reject links and special files before copying a local package.\"\"\"\n    import stat\n\n    for root, dirnames, filenames in os.walk(package_dir, followlinks=False):\n        root_path = Path(root)\n        for name in [*dirnames, *filenames]:\n            path = root_path / name\n            mode = path.lstat().st_mode\n            if stat.S_ISLNK(mode):\n                raise ValueError(f\"Workflow package contains symlink: {path}\")\n            if not stat.S_ISDIR(mode) and not stat.S_ISREG(mode):\n                raise ValueError(f\"Workflow package contains unsupported file: {path}\")","sourceCodeStart":919,"sourceCodeEnd":955,"githubUrl":"https://github.com/github/spec-kit/blob/bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c/src/specify_cli/workflows/_commands.py#L919-L955","documentation":"Error \"Archive must contain workflow.yml at its root or in exactly one top-level directory\" thrown in github/spec-kit.","triggerScenarios":"Thrown at src/specify_cli/workflows/_commands.py:937 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Repackage the archive so workflow.yml sits at its root or inside exactly one top-level directory."],"exampleFix":null,"handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c","analyzedAt":"2026-08-14T19:43:37.150Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}