TuxDev.

Troubleshooting & FAQ

Jun 20, 2026 • 4 min read
Troubleshooting FAQ Error Correction Logs Dependency Fix

This page covers common problems you might encounter and how to solve them.

🚨 Common Problems

App won’t start — “Address already in use”

Why it happens: Another program is already using port 8000 (or whatever port you configured).

Solution:

# Find what's using the port
sudo lsof -i :8000

# Either stop that program, or change the PORT in .env:
PORT=8001

Then restart the server.

App won’t start — “Python not found”

Why it happens: Python 3 is not installed or not on your PATH.

Solution:

# Install Python 3
# Debian/Ubuntu:
sudo apt install python3 python3-venv python3-pip

# macOS (Homebrew):
brew install python

# Verify installation:
python3 --version

“ffmpeg not found” or “Dependency missing”

Why it happens: ffmpeg is not installed, or the app can’t find it.

Solution:

# Debian/Ubuntu:
sudo apt update && sudo apt install ffmpeg

# macOS:
brew install ffmpeg

# Windows (Chocolatey):
choco install ffmpeg

# Verify:
ffmpeg -version

After installing, restart the app.

Can’t log in — “Invalid credentials”

Why it happens: You entered the wrong username or password.

Solutions:

  1. Default credentials: Try admin / admin123
  2. Check your .env file: Make sure ADMIN_USERNAME and ADMIN_PASSWORD are correct
  3. Reset the database: Delete the database file and restart (⚠️ this removes all data): 
    rm app/data/ytdlp.db
./run.sh
    A fresh database will be created with the admin credentials from your .env file.

Downloads keep failing

Why it happens: Several possible causes:

Cause What to check
URL is invalid Make sure the URL is correct and the video exists
Site changed yt-dlp might need an update — try updating from the System page
ffmpeg is missing Check the System page for dependency status
Rate limit If you set a rate limit, try removing it
Proxy issues If you configured a proxy, make sure it’s working
Disk space Check that your server has enough free disk space

First step: Update yt-dlp from the System page. Sites change frequently and yt-dlp updates keep things working.

The app feels slow

Why it happens: Usually due to one of these reasons:

  • Too many concurrent downloads: Lower max_concurrent_downloads in Settings
  • Rate limiting: You might have set a very low rate limit
  • Server resources: Your server might not have enough CPU/RAM
  • Network: Your internet connection might be the bottleneck

SSL certificate warning in browser

Why it happens: Self-signed certificates aren’t trusted by browsers.

Solution: Click “Advanced” → “Proceed” (the exact wording varies by browser). This warning is harmless for personal use.

For production, use a proper certificate from Let’s Encrypt behind a reverse proxy.

❓ Frequently Asked Questions

Is this free?

Yes. The app is self-hosted (you run it on your own server) and open-source. There are no subscriptions, no paywalls, no ads.

What sites are supported?

1000+ sites including YouTube, Vimeo, Twitter/X, TikTok, Instagram, Twitch, Facebook, Reddit, LinkedIn, Dailymotion, Bilibili, and many more. Check the yt-dlp supported sites list for the full list.

Can I download entire playlists?

Yes. Just paste the playlist URL and the app will download every video in it. You can also set up playlist monitoring to auto-download new videos as they’re published.

Can I download just the audio?

Yes. Use the Audio Only preset — it extracts audio and converts to MP3 at 320kbps.

Can more than one person use the app?

Currently, there’s one admin account. Multiple users can log in with the same credentials.

Where are my downloaded files?

By default, they’re in the downloads/ folder in the project directory. You can change this in Settings → Downloads → output_dir.

How do I update yt-dlp?

Go to System page and click Update. Or update manually:

pip install -U yt-dlp

Can I run this on a Raspberry Pi?

Yes. The app runs on any system with Python 3.9+ and ffmpeg. A Raspberry Pi 4 or 5 works fine for a few concurrent downloads.

Can I access it from the internet?

Yes. You can:

  1. Use a reverse proxy (Nginx, Caddy) with Let’s Encrypt for proper HTTPS
  2. Use Tailscale or Cloudflare Tunnel for secure remote access
  3. Enable SSL directly in the app (see Configuration Guide )

What data is stored?

The SQLite database stores:

  • Download jobs (URLs, progress, status)
  • Download history (completed and failed)
  • User account and session data
  • Application settings
  • Custom presets
  • Monitored playlist configurations

No data is sent anywhere else — it’s entirely self-contained on your server.

Will updates break my existing database?

The app runs lightweight migrations on startup — it adds new columns to existing tables without deleting your data. You can update without worry.

I still have a problem — what should I do?

  1. Check the log file: logs/ytdlp-web.log
  2. Try updating yt-dlp
  3. Restart the app
  4. Open an issue on GitLab with the log file contents and what you were trying to do