github/spec-kit · error · SystemExit

ERROR: Unknown option '{arg}'. Use --help for usage informat

Error message

ERROR: Unknown option '{arg}'. Use --help for usage information.

What it means

In _validate_safe_shared_directory(), an existing component on the path is not a directory (typically a regular file), so validation fails even though this validator tolerates missing paths. The message hardcodes 'Shared infrastructure directory' because this validator only serves shared-infra directory checks.

Source

Thrown at scripts/python/check_prerequisites.py:103

            paths_only = True
        elif arg == "--template":
            index += 1
            if index >= len(argv):
                print(
                    "ERROR: --template requires a template name",
                    file=sys.stderr,
                )
                raise SystemExit(1)
            template_name = argv[index]
        elif arg in {"--help", "-h"}:
            sys.stdout.write(HELP_TEXT)
            raise SystemExit(0)
        else:
            print(
                f"ERROR: Unknown option '{arg}'. Use --help for usage information.",
                file=sys.stderr,
            )
            raise SystemExit(1)
        index += 1

    return Args(
        json_mode=json_mode,
        require_tasks=require_tasks,
        include_tasks=include_tasks,
        paths_only=paths_only,
        template_name=template_name,
    )


def _dir_has_entries(path: Path) -> bool:
    try:
        return path.is_dir() and any(path.iterdir())
    except OSError:
        return False

View on GitHub (pinned to bf88c9f9a8)

Solutions

1. Inspect the named path from the error label; if it is not needed, delete it
2. If it may hold data, move it aside (mv X X.bak) and rerun so a real directory can be created
3. Search for the tool/script that created the file and fix it
4. Pre-flight check in automation: assert not (p.exists() and not p.is_dir()) for each parent

Example fix

# before
Path('.specify/shared').is_file()  # True -> raises during validate

# after
$ mv .specify/shared .specify/shared.bak
# rerun command; directory structure recreated

from pathlib import Path

def validate_no_collisions(project: Path, rel_dir: Path) -> None:
    cur = project
    for part in rel_dir.parts:
        cur = cur / part
        if cur.exists() and not cur.is_dir():
            raise RuntimeError(f'file blocks directory: {cur}')

validate_no_collisions(project_path, rel_dir)

try:
    _validate_safe_shared_directory(project_path, directory)
except ValueError as e:
    if 'is not a directory' in str(e):
        blocker = extract_path_from_message(e)
        blocker.rename(blocker.with_suffix('.bak'))
        _validate_safe_shared_directory(project_path, directory)
    else:
        raise

When it happens

Trigger: A file occupies a component of the shared-infra directory path: e.g. a file named 'shared' at .specify/shared, or .specify itself is a file, while the CLI validates a destination under it.

Common situations: Marker files or accidental buffers named like directories ('.specify' created by touch); scripts writing state files at directory paths; partial checkouts; conflicting file/dir names between workflow versions (a file in an old layout where a directory is expected after upgrade).

Related errors

• Error: --number requires a value
• 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/57df678c9e2c6caf. Report an issue: GitHub.