affaan-m/ECC · error · FalError

download declares an invalid or excessive size

Error message

download declares an invalid or excessive size

What it means

FalError raised inside download() when the HTTP response's Content-Length header is present but not an integer in the range 0..MAX_DOWNLOAD_BYTES. This catches servers declaring a corrupt (negative/non-numeric parse failure handled separately) or oversized body so the transfer is aborted before reading megabytes of data.

Solutions

  1. Check the file size via HEAD request before calling download() and skip files above MAX_DOWNLOAD_BYTES
  2. Download oversized assets outside this library (e.g. plain urllib/curl) if you genuinely need them
  3. If a proxy is mangling headers, bypass it or fix its Content-Length handling
  4. Increase MAX_DOWNLOAD_BYTES in the module only deliberately, understanding the memory/disk tradeoff

Example fix

// before
download(huge_video_url, out)
// after
req = urllib.request.Request(huge_video_url, method="HEAD")
size = int(urllib.request.urlopen(req).headers["Content-Length"])
if size > MAX_DOWNLOAD_BYTES:
    raise SystemExit(f"asset too large: {size} bytes")
download(huge_video_url, out)
Defensive patterns

Strategy: validation

Validate before calling

import urllib.request
req = urllib.request.Request(url, method="HEAD")
with urllib.request.urlopen(req) as r:
    clen = r.headers.get("Content-Length")
if clen is not None and int(clen) > MAX_DOWNLOAD_BYTES:
    raise SystemExit(f"asset too large to download: {clen} bytes")

Try / catch

try:
    download(url, dest)
except FalError as e:
    if "excessive size" in str(e):
        logging.error("download declared size exceeds cap for %s", safe_url(url))
    raise

Prevention

When it happens

Trigger: Downloading a file whose server returns a Content-Length header larger than MAX_DOWNLOAD_BYTES (e.g. a multi-gigabyte video); a malformed Content-Length value that int() cannot parse (raises before this check) or a negative value.

Common situations: Pointing download() at a very large asset that exceeds the library's size policy; a proxy injecting a bogus Content-Length header; misusing download() for files it was not designed for (huge raw footage).

Understand the failure class

Background: "File too large" / "file size exceeds limit" errors: why libraries cap file sizes and how to fix them — this error's family across 46 libraries.

Related errors

AI-assisted analysis of affaan-m/ECC@8321021c54 (2026-09-16). Data as JSON: /api/errors/64f19f324f8fcde0. Report an issue: GitHub.

Appendix: source

Thrown at skills/taste-application/scripts/falapi.py:701

    if is_dry_run():
        dest.parent.mkdir(parents=True, exist_ok=True)
        dest.write_bytes(b"taste-forge dry-run placeholder\n")
        log.info("[dry-run] would download from %s", safe_url(url))
        return dest

    require_live()
    _validate_download_url(url)
    dest.parent.mkdir(parents=True, exist_ok=True)
    log.info("downloading from %s", safe_url(url))
    req = urllib.request.Request(url, headers={"User-Agent": "taste-forge"})
    opener = urllib.request.build_opener(_SafeRedirect())
    temporary = None
    try:
        with opener.open(req, timeout=300) as resp:
            declared = getattr(resp, "headers", {}).get("Content-Length")
            expected = int(declared) if declared is not None else None
            if expected is not None and not 0 <= expected <= MAX_DOWNLOAD_BYTES:
                raise FalError("download declares an invalid or excessive size")
            with tempfile.NamedTemporaryFile(dir=dest.parent, prefix=".taste-download-",
                                             delete=False) as fh:
                temporary = Path(fh.name)
                total = 0
                while True:
                    chunk = resp.read(min(1024 * 1024, MAX_DOWNLOAD_BYTES - total + 1))
                    if not chunk:
                        break
                    total += len(chunk)
                    if total > MAX_DOWNLOAD_BYTES:
                        raise FalError("download exceeds maximum allowed size")
                    fh.write(chunk)
                if expected is not None and total != expected:
                    raise FalError("download length does not match declared size")
        os.replace(temporary, dest)
        temporary = None
    except FalError:
        raise

View on GitHub (pinned to 8321021c54)