github/spec-kit · error · SystemExit

Error: --number requires a value

Error message

Error: --number requires a value

What it means

While walking/creating the shared-infrastructure directory, _ensure_safe_shared_directory() found an existing path component that is a regular file (or other non-directory), so it cannot create or descend into it. The context string names the kind of directory being prepared (default 'shared infrastructure directory').

Solutions

1. Identify the offending file from the label in the error and inspect it (cat .specify/shared) — if it is junk, delete it
2. If it holds real content, rename it (mv .specify/shared .specify/shared.bak) and rerun so the directory can be created
3. Check for scripts/plugins that create marker files with directory names and disable that behavior
4. In automation, pre-flight: if path.exists() and not path.is_dir(): remove or relocate before running the CLI

Example fix

# before
$ ls .specify
shared   # regular file, not directory

# after
$ mv .specify/shared .specify/shared.file.bak
$ specify <command>  # directory recreated cleanly

from pathlib import Path

def no_file_dir_collision(project: Path, rel_dir: Path) -> bool:
    cur = project
    for part in rel_dir.parts:
        cur = cur / part
        if cur.exists() and not cur.is_dir():
            return False
    return True

assert no_file_dir_collision(project_path, rel_dir)

try:
    _ensure_safe_shared_directory(project_path, directory)
except ValueError as e:
    if 'is not a directory' in str(e):
        # path from the label is a file; move it aside and retry
        raise SystemExit(f'file blocking directory: {e}') from e
    raise

When it happens

Trigger: A file exists where a directory is expected: e.g. a file named 'shared' at .specify/shared while the CLI tries to use .specify/shared/scripts; or .specify itself is a regular file (e.g. created by 'touch .specify' or a bad tool writing a marker file).

Common situations: A previous tool or script wrote a file with the same name as the directory; typo'd commands like touch .specify; editor plugins saving a buffer named after the directory; partial checkouts where a directory became a file.

Related errors

• ERROR: Unknown option
• Error: branch_template must include the
• errors.join('; ')
• Refusing to scaffold outside the repository root
• specify event } ( }) failed: }

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

Appendix: source

Thrown at extensions/git/scripts/python/create_new_feature_branch.py:110

    i = 0
    while i < len(argv):
        arg = argv[i]
        if arg == "--json":
            args.json_mode = True
        elif arg == "--dry-run":
            args.dry_run = True
        elif arg == "--allow-existing-branch":
            args.allow_existing = True
        elif arg == "--short-name":
            if i + 1 >= len(argv) or argv[i + 1].startswith("--"):
                _err("Error: --short-name requires a value")
                raise SystemExit(1)
            i += 1
            args.short_name = argv[i]
        elif arg == "--number":
            if i + 1 >= len(argv) or argv[i + 1].startswith("--"):
                _err("Error: --number requires a value")
                raise SystemExit(1)
            i += 1
            args.branch_number = argv[i]
            if not re.fullmatch(r"[0-9]+", args.branch_number):
                _err("Error: --number must be a non-negative integer")
                raise SystemExit(1)
        elif arg == "--timestamp":
            args.use_timestamp = True
        elif arg in ("--help", "-h"):
            print(HELP_TEXT)
            raise SystemExit(0)
        else:
            args.description_parts.append(arg)
        i += 1
    return args


# ── Core helpers loading ─────────────────────────────────────────────────────

View on GitHub (pinned to bf88c9f9a8)