github/spec-kit · error · ExtensionError

Could not safely write download file: {exc}

Error message

Could not safely write download file: {exc}

What it means

The transient download file was opened successfully, but writing the archive bytes, flushing, or rewinding it raised OSError — wrapped as 'Could not safely write download file'. The fd is wrapped with os.fdopen(download_fd, 'w+b') and the 50 MiB payload is written in one go before detection runs.

Source

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

    download_file = None
    try:
        try:
            download_fd = _safe_open_download_zip(
                project_root, download_dir, archive_filename
            )
        except OSError as exc:
            raise ExtensionError(
                f"Could not safely create download file: {exc}"
            ) from exc

        try:
            download_file = os.fdopen(download_fd, "w+b")
            download_fd = -1
            download_file.write(archive_data)
            download_file.flush()
            download_file.seek(0)
        except OSError as exc:
            raise ExtensionError(
                f"Could not safely write download file: {exc}"
            ) from exc

        format_source = (
            final_url
            if archive_format_from_name(final_url) is not None
            else url
        )
        try:
            detect_archive_format(
                archive_path,
                archive_file=download_file,
                source_name=format_source,
                content_type=content_type,
                error_type=ExtensionError,
            )
        except ExtensionError as exc:
            raise ExtensionError(

View on GitHub (pinned to bf88c9f9a8)

Solutions

1. Check available space where the project lives: `df -h .` and free space if the download (up to 50 MiB) doesn't fit
2. Raise container disk size or move the project off tmpfs if applicable
3. Retry after cleaning stale files under the extension download cache area in .specify
4. If storage is genuinely unreliable, download elsewhere (`curl -fL`) and install from the local archive path

import shutil

def disk_fits_download(path: str, cap_bytes: int = 50 * 1024 * 1024) -> bool:
    usage = shutil.disk_usage(path)
    return usage.free > cap_bytes * 2  # archive + extraction headroom

from specify_cli.extensions import ExtensionError

try:
    install_from_url_cmd(project_root, url, speckit_version)
except ExtensionError as e:
    if 'Could not safely write download file' in str(e):
        # errno ENOSPC in __cause__: free space or install from local archive

When it happens

Trigger: `specify extension install <url>` when the filesystem fills up mid-write (ENOSPC), a quota is exceeded, the file is on a tmpfs that overflows, or the container/OS kills the handle (EIO on failing storage).

Common situations: Small CI container with a tiny /tmp or workspace disk; tmpfs-backed project dir in RAM-constrained environments; flaky network storage. The 50 MiB cap makes single-archive sizes predictable, so this is almost always capacity, not code.

Related errors

• Could not safely create download file: {exc}
• {exc}
• Directory not found: {source_path}
• No extension.yml found in {source_path}
• Could not read manifest {path}: {e}

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