github/spec-kit · error · FileExistsError

Refusing to overwrite existing scaffold file(s): {labels}

Error message

Refusing to overwrite existing scaffold file(s): {labels}

What it means

scaffold_integration is intentionally non-destructive: before writing the new package's __init__.py and tests/integrations/test_integration_<pkg>.py it checks whether either file already exists, and raises FileExistsError (a distinct type from the ValueError guards) listing the offending relative paths. This protects hand-written or previously scaffolded integrations from being overwritten.

Source

Thrown at src/specify_cli/integration_scaffold.py:234

    integrations_root = project_root / "src" / "specify_cli" / "integrations"
    tests_root = project_root / "tests" / "integrations"
    if not _is_spec_kit_repo_root(project_root):
        raise ValueError("Run this command from the Spec Kit repository root.")

    package_name = _package_name(clean_key)
    class_name = _class_name(clean_key)
    integration_dir = integrations_root / package_name
    integration_file = integration_dir / "__init__.py"
    test_file = tests_root / f"test_integration_{package_name}.py"

    for target in (integration_file, test_file):
        _assert_safe_scaffold_target(project_root, target)

    existing = [path for path in (integration_file, test_file) if path.exists()]
    if existing:
        labels = ", ".join(path.relative_to(project_root).as_posix() for path in existing)
        raise FileExistsError(f"Refusing to overwrite existing scaffold file(s): {labels}")

    created_integration_dir = not integration_dir.exists()
    try:
        integration_dir.mkdir(exist_ok=True)
        integration_file.write_text(
            _integration_content(
                key=clean_key,
                class_name=class_name,
                integration_type=normalized_type,
            ),
            encoding="utf-8",
        )
        test_file.write_text(
            _test_content(
                key=clean_key,
                class_name=class_name,
                integration_type=normalized_type,
            ),

View on GitHub (pinned to bf88c9f9a8)

Solutions

1. Choose a different, unique integration key for the new agent.
2. If the previous files are disposable, delete or rename the files listed in the error message and re-run the scaffold.
3. If the existing integration is real work, edit it in place rather than re-scaffolding.

Example fix

# before
ValueError/FileExistsError: Refusing to overwrite existing scaffold file(s): src/specify_cli/integrations/my_agent/__init__.py
# after
$ git rm src/specify_cli/integrations/my_agent/__init__.py tests/integrations/test_integration_my_agent.py
# then re-run scaffold

pkg = key.replace("-", "_")
paths = [
    root / "src" / "specify_cli" / "integrations" / pkg / "__init__.py",
    root / "tests" / "integrations" / f"test_integration_{pkg}.py",
]
if any(p.exists() for p in paths):
    raise SystemExit(f"scaffold files already exist: {[str(p) for p in paths if p.exists()]}")

try:
    scaffold_integration(root, key, itype)
except FileExistsError as exc:
    print(str(exc))  # lists existing files; pick a new key or remove them deliberately

When it happens

Trigger: Running the scaffold twice with the same key; scaffolding a key whose package already exists (e.g. re-running 'specify init'-era scaffold for 'gemini'); an existing test file named test_integration_<package_name>.py colliding even when the package dir is new.

Common situations: Re-running a scaffold command after a partial earlier run; two agents whose keys normalize to the same package_name (hyphens to underscores); forgetting a previous experiment with the same key exists.

Related errors

• Refusing to scaffold outside the repository root: {target}
• Refusing to scaffold through symlinked path: {label}
• specify event ${{command}} (${{event}}) failed: ${{(e as Err
• errors.join('; ')
• Error: --short-name requires a value

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