github/spec-kit · error · ValueError

Archive must contain workflow.yml at its root or in exactly

Error message

Archive must contain workflow.yml at its root or in exactly one top-level directory

What it means

Error "Archive must contain workflow.yml at its root or in exactly one top-level directory" thrown in github/spec-kit.

Source

Thrown at src/specify_cli/workflows/_commands.py:937

            "[yellow]Warning:[/yellow] Workflow installed, but its backup file "
            f"could not be cleaned up: {_escape_markup(str(exc))}. Remove it "
            f"manually: {_escape_markup(str(backup_file))}"
        )


def _workflow_package_root(extracted_root: Path) -> Path:
    """Resolve a root-level or single-nested workflow package."""
    if (extracted_root / "workflow.yml").is_file():
        return extracted_root
    entries = list(extracted_root.iterdir())
    if (
        len(entries) == 1
        and entries[0].is_dir()
        and not entries[0].is_symlink()
        and (entries[0] / "workflow.yml").is_file()
    ):
        return entries[0]
    raise ValueError(
        "Archive must contain workflow.yml at its root or in exactly one "
        "top-level directory"
    )


def _validate_local_workflow_package(package_dir: Path) -> None:
    """Reject links and special files before copying a local package."""
    import stat

    for root, dirnames, filenames in os.walk(package_dir, followlinks=False):
        root_path = Path(root)
        for name in [*dirnames, *filenames]:
            path = root_path / name
            mode = path.lstat().st_mode
            if stat.S_ISLNK(mode):
                raise ValueError(f"Workflow package contains symlink: {path}")
            if not stat.S_ISDIR(mode) and not stat.S_ISREG(mode):
                raise ValueError(f"Workflow package contains unsupported file: {path}")

View on GitHub (pinned to bf88c9f9a8)

Solutions

1. Repackage the archive so workflow.yml sits at its root or inside exactly one top-level directory.

When it happens

Trigger: Thrown at src/specify_cli/workflows/_commands.py:937 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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