github/spec-kit · error · ValueError

Downloaded extension archive must contain exactly one top-le

Error message

Downloaded extension archive must contain exactly one top-level directory

What it means

Error "Downloaded extension archive must contain exactly one top-level directory" thrown in github/spec-kit.

Source

Thrown at src/specify_cli/extensions/_commands.py:1944

                            raise ValueError(
                                "Archive must use canonical 'extension.yml' casing"
                            )
                        canonical_root_manifest = next(
                            (
                                entry
                                for entry in root_manifest_entries
                                if entry.name == "extension.yml"
                            ),
                            None,
                        )
                        if canonical_root_manifest is not None:
                            manifest_path = canonical_root_manifest
                        else:
                            top_level_dirs = [
                                entry for entry in top_level if entry.is_dir()
                            ]
                            if len(top_level_dirs) != 1:
                                raise ValueError(
                                    "Downloaded extension archive must contain exactly "
                                    "one top-level directory"
                                )
                            manifest_root = top_level_dirs[0]
                            nested_manifest_entries = [
                                entry
                                for entry in manifest_root.iterdir()
                                if entry.name.casefold() == "extension.yml"
                            ]
                            if any(
                                entry.name != "extension.yml"
                                for entry in nested_manifest_entries
                            ):
                                raise ValueError(
                                    "Archive must use canonical 'extension.yml' casing"
                                )
                            manifest_path = next(
                                (

View on GitHub (pinned to bf88c9f9a8)

Solutions

1. Repackage the archive so it contains exactly one top-level directory holding the extension.

When it happens

Trigger: Thrown at src/specify_cli/extensions/_commands.py:1944 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/dbd13d561313e254. Report an issue: GitHub.