# ReClip Download Timeout: How the 5-Minute Limit Works

> Understand the ReClip download timeout. Learn why jobs fail after 5 minutes and how the 300-second limit affects your yt-dlp subprocesses.

- Repository: [Avery Gan/reclip](https://github.com/averygan/reclip)
- Tags: internals
- Published: 2026-09-03

---

**ReClip enforces a strict 300-second (5-minute) timeout on all video download jobs, aborting any `yt-dlp` subprocess that exceeds this limit and marking the job as failed.**

The **download timeout for ReClip jobs** is hardcoded into the core download worker to prevent hung processes and resource exhaustion. When a user submits a URL for processing, the backend delegates to `yt-dlp` via a subprocess call with explicit time boundaries. Understanding this mechanism helps developers tune expectations and handle failure states gracefully.

## Where the Timeout Is Defined

The timeout logic resides in [`app.py`](https://github.com/averygan/reclip/blob/main/app.py), specifically within the `run_download()` function.

### The 300-Second Subprocess Call

ReClip invokes `yt-dlp` using `subprocess.run()` with `timeout=300`:

```python

# app.py (line 48)

result = subprocess.run(
    cmd,
    capture_output=True,
    text=True,
    timeout=300  # 5 minutes

)

```

This parameter is passed directly to Python's standard library subprocess module. If `yt-dlp` does not complete within 300 seconds, Python raises `subprocess.TimeoutExpired`.

### Timeout Exception Handling

The exception is caught and mapped to a user-visible error state at lines 84-86:

```python

# app.py (lines 84-86)

except subprocess.TimeoutExpired:
    job["status"] = "error"
    job["error"] = "Download timed out (5 min limit)"

```

No retry logic is implemented—the job terminates immediately upon timeout.

## Checking Job Status After Submission

Clients can poll the status endpoint to detect timeout failures:

```python
import requests

# Start a download

resp = requests.post(
    "http://localhost:5000/api/download",
    json={"url": "https://www.youtube.com/watch?v=example", "format": "video"}
)
job_id = resp.json()["job_id"]

# Check status

status = requests.get(f"http://localhost:5000/api/status/{job_id}").json()
print(status)

```

**Example timeout response:**

```json
{
  "status": "error",
  "error": "Download timed out (5 min limit)",
  "filename": null
}

```

## Why 5 Minutes?

The **ReClip download timeout** balances two competing constraints:

1. **User experience** — Most short-form and standard-length videos complete well under 5 minutes on reasonable connections
2. **Resource protection** — Prevents indefinite blocking of worker threads by slow servers, large files, or network stalls

This is a static value; no configuration flag or environment variable overrides it in the current implementation.

## Key Files Controlling Download Behavior

| File | Purpose |
|------|---------|
| [`app.py`](https://github.com/averygan/reclip/blob/main/app.py) | Core Flask application; contains `run_download()` with the 300s timeout enforcement |
| `Dockerfile` | Container build configuration for the Flask service |
| [`requirements.txt`](https://github.com/averygan/reclip/blob/main/requirements.txt) | Python dependencies including Flask |

## Summary

- **ReClip download jobs time out after exactly 300 seconds (5 minutes)**
- Timeout is enforced via `subprocess.run(timeout=300)` in [`app.py`](https://github.com/averygan/reclip/blob/main/app.py)
- Expired jobs receive status `"error"` with message `"Download timed out (5 min limit)"`
- No retry mechanism exists; clients must resubmit failed URLs
- The limit is hardcoded and not user-configurable

## Frequently Asked Questions

### Can I increase the ReClip download timeout?

No. The 300-second value is hardcoded in [`app.py`](https://github.com/averygan/reclip/blob/main/app.py) at line 48 and line 84. To modify it, you must edit the source and rebuild the application.

### What happens to partially downloaded files on timeout?

The timeout triggers `subprocess.TimeoutExpired`, which kills the `yt-dlp` process immediately. Any partial files remain in the download directory but are not tracked in the job status. The job record shows only the timeout error.

### Does ReClip retry failed downloads automatically?

No. According to the source code in [`app.py`](https://github.com/averygan/reclip/blob/main/app.py), timeout exceptions set the job status to `"error"` and stop processing. Clients must detect the failure via the status API and submit a new request if desired.

### Why does ReClip use `yt-dlp` instead of a Python library?

The subprocess approach isolates `yt-dlp`'s complex dependency chain and frequent updates from the Flask application. The 300-second timeout acts as a safeguard against any hang within that external process.