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').

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)

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 '{arg}'. Use --help for usage informat
• specify event ${{command}} (${{event}}) failed: ${{(e as Err
• errors.join('; ')
• Error: branch_template must include the {number} token so ge
• Refusing to scaffold outside the repository root: {target}

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