# How to Troubleshoot ReClip "Video Not Found" Errors: A Complete Debugging Guide

> Troubleshoot ReClip video not found errors. This guide details debugging yt-dlp integration issues and resolving common ReClip video access problems.

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

---

**ReClip "Video not found" errors occur when the underlying `yt-dlp` command fails to locate a video, and the error is propagated from [`app.py`](https://github.com/averygan/reclip/blob/main/app.py) as a JSON response with an `error` field.**

ReClip is a lightweight Flask-based video downloader that wraps **yt-dlp** to handle video metadata retrieval and downloads. When the service cannot access a requested video, it surfaces this failure directly to clients. This guide explains exactly where these errors originate in the ReClip source code, common root causes, and a systematic workflow to resolve them.

## Where "Video Not Found" Errors Originate in ReClip

The error handling logic is centralized in [`app.py`](https://github.com/averygan/reclip/blob/main/app.py). Understanding these three code locations helps diagnose failures quickly.

### Info Endpoint: Metadata Retrieval

In [`app.py`](https://github.com/averygan/reclip/blob/main/app.py) lines [97-108](https://github.com/averygan/reclip/blob/main/app.py#L97-L108), the `/api/info` route executes:

```python
command = ["yt-dlp", "--no-playlist", "-j", url]
result = subprocess.run(command, capture_output=True, text=True)

```

If `result.returncode != 0`, the code extracts the last line of `stderr` and returns `{"error": "<message>"}`. This is the primary path for "Video not found" responses.

### Download Endpoint: Background Jobs

In [`app.py`](https://github.com/averygan/reclip/blob/main/app.py) lines [66-84](https://github.com/averygan/reclip/blob/main/app.py#L66-L84), the `/api/download` endpoint spawns a thread that runs `yt-dlp` with format arguments. On failure, it stores:

```python
job["error"] = result.stderr.strip().split("\n")[-1]

```

This error surfaces later via the status endpoint.

### JSON Parsing Utility

In [`app.py`](https://github.com/averygan/reclip/blob/main/app.py) lines [16-29](https://github.com/averygan/reclip/blob/main/app.py#L16-L29), the `get_info()` function reads `yt-dlp` output line-by-line. If no valid JSON is extracted, a `ValueError` is caught and converted to an error response.

## Common Causes of ReClip "Video Not Found" Errors

| Cause | Verification Command |
|-------|-------------------|
| **Invalid or malformed URL** | `yt-dlp --no-playlist -j "<url>"` |
| **Private/age-restricted video** | Check for `ERROR: This video is private` or `ERROR: This video is age-restricted` |
| **Geoblocked content** | Test `yt-dlp --geo-bypass "<url>"` or use a VPN |
| **Removed/unavailable video** | Confirm in browser — YouTube shows "Video unavailable" |
| **Outdated yt-dlp extractor** | `yt-dlp --version` then `pip install -U yt-dlp` |
| **Network/DNS issues in container** | `docker exec -it reclip curl -I https://www.youtube.com` |
| **Rate-limiting or CAPTCHA** | Look for `ERROR: unable to download webpage`; try `--cookies` or wait |

## Step-by-Step Troubleshooting Workflow

### Step 1: Validate the Request URL

Ensure the client sends a clean URL. The code calls `.strip()`, but extra encoding or spaces can still cause issues:

```bash
curl -X POST -H "Content-Type: application/json" \
     -d '{"url":"https://youtu.be/abc123"}' \
     http://localhost:8899/api/info

```

### Step 2: Replicate the yt-dlp Command Manually

Mirror exactly what ReClip executes:

```bash
yt-dlp --no-playlist -j "https://youtu.be/abc123"

```

- **Success**: Single JSON line with video metadata
- **Failure**: Error line like `ERROR: Video unavailable`

### Step 3: Test Inside the Docker Container

If running containerized, verify the environment:

```bash
docker exec -it reclip /bin/bash
yt-dlp --no-playlist -j "https://youtu.be/abc123"

```

Also verify network connectivity:

```bash
curl -I https://www.youtube.com
nslookup youtube.com

```

### Step 4: Inspect the Job Error Field

For download failures, retrieve the stored error:

```bash

# Start download (returns job_id)

curl -X POST -H "Content-Type: application/json" \
     -d '{"url":"https://youtu.be/XYZ","format":"video"}' \
     http://localhost:8899/api/download

# Check status

curl http://localhost:8899/api/status/<job_id>

```

Expected error response:

```json
{"status":"error","error":"ERROR: Video unavailable","filename":null}

```

### Step 5: Upgrade yt-dlp

YouTube frequently changes page structures. Update the extractor:

```bash
pip install -U yt-dlp

```

Or modify the `Dockerfile` to ensure latest version:

```dockerfile
FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
RUN pip install -U yt-dlp  # Explicit upgrade

COPY . .
CMD ["python", "app.py"]

```

### Step 6: Handle Access-Restricted Content

For private or age-restricted videos, provide authentication:

```bash
yt-dlp --cookies "cookies.txt" --no-playlist -j "<url>"

```

### Step 7: Implement Retry Logic

Temporary blocks often resolve within minutes. Add exponential back-off in your client:

```python
import time

for attempt in range(3):
    response = request_video(url)
    if "error" not in response:
        break
    time.sleep(2 ** attempt)  # 1s, 2s, 4s

```

## Key Source Files in ReClip

| File | Purpose | Lines of Interest |
|------|---------|-----------------|
| [`app.py`](https://github.com/averygan/reclip/blob/main/app.py) | Flask server with `/api/info` and `/api/download` routes | 16-29 (parsing), 66-84 (download), 97-108 (info) |
| [`requirements.txt`](https://github.com/averygan/reclip/blob/main/requirements.txt) | Python dependencies including `yt-dlp` | — |
| `Dockerfile` | Container build instructions | Add `pip install -U yt-dlp` for updates |
| [`templates/index.html`](https://github.com/averygan/reclip/blob/main/templates/index.html) | Frontend that calls the API | Error display logic |

## Summary

- **ReClip "Video not found" errors originate from `yt-dlp` failures** surfaced through [`app.py`](https://github.com/averygan/reclip/blob/main/app.py) endpoints as JSON error responses.
- **Diagnose systematically**: test URL validity, replicate `yt-dlp` commands manually, verify container network access, and inspect `job["error"]` values.
- **Most fixes involve updating `yt-dlp`**, handling authentication for restricted content, or resolving network/DNS issues in containerized deployments.

## Frequently Asked Questions

### What does the "Video not found" error mean in ReClip?

The error indicates that `yt-dlp` — the tool ReClip uses to fetch video data — could not locate or access the requested video. According to the ReClip source code in [`app.py`](https://github.com/averygan/reclip/blob/main/app.py), this occurs when `yt-dlp` exits with a non-zero status, and the last line of `stderr` is captured and returned as `{"error": "..."}`.

### How can I check if yt-dlp is causing the error?

Run the exact command ReClip uses: `yt-dlp --no-playlist -j "YOUR_URL"`. If this fails with the same error message, the issue is with `yt-dlp` rather than ReClip's code. Check for outdated versions with `yt-dlp --version` and upgrade with `pip install -U yt-dlp`.

### Why does ReClip work for some YouTube videos but not others?

YouTube applies different restrictions: geoblocking, age verification, private videos, and rate-limiting. ReClip passes these through transparently. Use `yt-dlp --geo-bypass`, provide `--cookies` for authenticated content, or wait and retry if rate-limited.

### How do I fix network errors inside the ReClip Docker container?

Exec into the running container with `docker exec -it reclip /bin/bash` and test connectivity using `curl -I https://www.youtube.com` and `nslookup youtube.com`. If DNS or routing fails, check your Docker network configuration or host firewall rules.