Skip to content

Troubleshooting

This guide separates standalone binary installs, uv tool installs, and developer checkouts.

If you installed VDL using the standalone installer or downloaded a release binary, repair VDL by updating or reinstalling VDL itself. Changing a local Python environment will not update the packaged VDL binary.

The standalone installer is safe to rerun: - if VDL is missing, it installs - if VDL is older, it updates - if the same version is already installed, it does nothing - if dependencies are missing, it stops before replacing the current binaries

First: Identify Your Install Type

Choose the branch that matches how you installed VDL:

  1. Standalone binary / installer

  2. Examples: downloaded vdl.exe, used the platform installer script, or installed vdl into ~/.local/bin or %USERPROFILE%\.local\bin

  3. uv tool install

  4. Example: installed VDL with uv tool install vdl

  5. Developer checkout

  6. Example: cloned the repository and run VDL with uv run

Universal Checks

Run these first regardless of install type:

vdl doctor
vdl --version

Check that:

  • ffmpeg is available
  • ffprobe is available
  • yt-dlp is available
  • downloads, config, state, cache, and log paths are correct for your platform
  • vdl-mcp availability matches your install type

Expected Default Paths

Windows

  • Downloads: C:\Users\<user>\Downloads\VDL
  • Config: %APPDATA%\vdl
  • State: %LOCALAPPDATA%\vdl
  • Cache: %LOCALAPPDATA%\vdl\cache
  • Logs: %LOCALAPPDATA%\vdl\logs
  • Binary install location: %USERPROFILE%\.local\bin

macOS / Linux

  • Downloads: ~/Downloads/VDL
  • Config: ~/.config/vdl
  • State: ~/.local/state/vdl
  • Cache: ~/.cache/vdl
  • Logs: ~/.local/state/vdl/logs
  • Binary install location: ~/.local/bin

Standalone Binary / Installer

Use this section if you installed VDL through the release binary or installer script.

Command not found: vdl

Problem: Your shell cannot find vdl.

What to do:

  1. Find the installed binary location.
  2. Make sure that directory is on PATH.
  3. Re-open your shell after changing PATH.
  4. Run:
vdl --version
vdl doctor

Typical binary locations:

  • macOS/Linux: ~/.local/bin/vdl
  • Windows: %USERPROFILE%\.local\bin\vdl.exe

If the command is still not found, run VDL by full path first, then fix PATH.

macOS / Linux example

~/.local/bin/vdl --version

Windows PowerShell example

& "$env:USERPROFILE\.local\bin\vdl.exe" --version

Problem: vdl doctor or a download reports a yt-dlp problem.

What this means for binary installs:

The standalone VDL binary includes its own packaged runtime. Updating tools in a separate local Python environment will not update the packaged VDL binary.

What to do:

  1. Update or reinstall VDL itself.
  2. Run:
vdl doctor
  1. Retry the download.

  2. If the problem remains, collect:

  3. vdl doctor output

  4. vdl --version
  5. the exact download error
  6. the URL type, for example single video, playlist, mix, or crawl page

ffmpeg or ffprobe missing

Problem: Downloads fail with errors such as:

ERROR: You have requested merging of multiple formats but ffmpeg is not installed.

Cause: Some sites provide separate video and audio streams. VDL needs ffmpeg to merge them.

What to do:

  1. Install ffmpeg for your platform.
  2. Make sure both ffmpeg and ffprobe are on PATH.
  3. Run:
vdl doctor
  1. Retry the download only after both tools show as available.

For standalone binary installs, this should normally be caught during installation because the installer stops until these dependencies are available.

macOS

brew install ffmpeg
vdl doctor

Ubuntu / Debian

sudo apt-get update
sudo apt-get install ffmpeg
vdl doctor

Windows

Install ffmpeg using your preferred Windows method, then ensure the folder containing ffmpeg.exe and ffprobe.exe is on PATH.

After installation, verify:

ffmpeg -version
ffprobe -version
vdl doctor

Windows binary: prompt shows the wrong output path

Problem: On Windows, the interactive prompt shows or accepts a Unix-style path such as:

/Users/David/Downloads

or shows a test/temp directory instead of the user Downloads folder.

Expected Windows default:

C:\Users\<user>\Downloads\VDL

What this means:

  • a Unix-style path was entered during the prompt, or
  • the packaged binary leaked a test/home-path assumption into runtime behavior, or
  • an old config file contains a stale path

What to do:

  1. Run:
vdl doctor
  1. Confirm downloads, config, state, cache, and log paths are Windows-native.
  2. If the default path is correct, press Enter to accept it.
  3. If you enter a custom path on Windows, use a Windows path:
C:\Users\David\Downloads\VDL
  1. If the wrong path persists, check your config file under %APPDATA%\vdl.

vdl-mcp not found

Problem: The MCP command is missing.

What to do for standalone binaries:

  1. Verify the release installed both:

  2. vdl

  3. vdl-mcp
  4. Run:
vdl-mcp --help
vdl doctor
  1. If vdl exists but vdl-mcp does not, update or reinstall VDL.

Installed version is newer than the release target

Problem: Re-running the installer says the installed version is newer than the target version.

What this means: You already have a newer managed standalone install than the release the installer is targeting.

What to do:

  1. Do nothing if you meant to stay on the newer version.
  2. Re-run the installer with force only if you intentionally want to reinstall the older target version.

Existing standalone install is broken or incomplete

Problem: The installer says the managed install is broken or incomplete.

What this means: The installer found vdl or vdl-mcp in the managed install directory, but the binaries were not healthy enough to trust for an in-place no-op or update decision.

What to do:

  1. Re-run the installer with force.
  2. Verify the repaired install with:
vdl --version
vdl doctor

uv Tool Install

Use this section only if you intentionally installed VDL with uv tool.

Repair or update VDL

uv tool upgrade vdl
vdl doctor

If the tool environment seems broken, remove and reinstall the tool with uv tool.

MCP with uv tool installs

If vdl-mcp is missing, reinstall or upgrade the uv tool install, then verify:

vdl-mcp --help
vdl doctor

Developer Checkout

Use this section only if you are running from a local clone of the repository.

Refresh the checkout

uv sync --all-extras --dev
uv run vdl doctor

Run from the checkout

uv run vdl --version
uv run vdl doctor

MCP from the checkout

uv run vdl-mcp --help

Download Failures

Unsupported URL

Problem: VDL does not recognize the URL.

What to do:

  1. Verify the URL is valid and publicly accessible.
  2. Run:
vdl doctor
  1. Update or reinstall VDL using the same install type you already use.
  2. If the site requires authentication, retry with cookies.

Example:

vdl download "URL" --cookies-from-browser chrome

Bot detection or age restriction

Problem: Download fails with a bot-detection or age-restriction error.

What to do:

  1. Retry with cookies from a logged-in browser:
vdl download "URL" --cookies-from-browser chrome
  1. If that fails, try another installed browser:
vdl download "URL" --cookies-from-browser firefox
  1. Update or reinstall VDL using the same install type you already use.
  2. Retry the same URL after the update.

Download appears to hang

Problem: The app appears stuck.

What to do:

  1. Press Ctrl+C to cancel.
  2. Check your network connection.
  3. Try a different URL.
  4. Run:
vdl doctor

Interactive note: if the results table already shows completed, skipped, or failed, and the prompt returns to:

URL or local file path:

VDL is waiting for the next input. Type a new URL or type quit to exit.

Subtitle rate limit errors

Problem: Some downloads fail with an error like:

Unable to download video subtitles for 'en': HTTP Error 429: Too Many Requests

What this means: The host rate-limited subtitle downloads. The video may still be downloadable without subtitles.

What to do:

  1. Retry the failed items without subtitles.
  2. In interactive mode, choose the retry option that disables subtitles if offered.
  3. In CLI mode, run the download again with subtitles disabled if your command enabled subtitles.
  4. Use --if-exists skip so already completed video files are not downloaded again.

Output file already exists

VDL is designed to avoid unnecessary duplicate downloads. A completed video file should be skipped when skip mode is used. A .part file should not be treated as completed; it should resume or continue.

Use --if-exists when you need explicit behavior:

vdl download "URL" --if-exists skip
vdl download "URL" --if-exists rename
vdl download "URL" --if-exists overwrite
vdl download "URL" --if-exists fail

Meaning:

  • skip: do not download again if a completed matching file exists
  • rename: save with a new name
  • overwrite: replace the existing file
  • fail: stop with an error if a completed matching file exists

Playlist Issues

Playlist is empty or no items found

Problem: Playlist resolution returns zero items.

What to do:

  1. Verify the URL is actually a playlist.
  2. Run:
vdl resolve "URL" --json
  1. If the playlist requires authentication, retry with cookies:
vdl resolve "URL" --cookies-from-browser chrome
  1. Update or reinstall VDL using the same install type you already use.

In interactive mode, VDL should not ask you to select from 0 items. If that happens, collect the exact URL and prompt output.

URL is part of a playlist

When a YouTube video URL includes a playlist parameter, VDL may ask:

This URL is part of a playlist. What would you like to download?
  1. Just this video
  2. All videos in the playlist

Choose single video if you only want the current video. Choose playlist if you want VDL to resolve and download playlist items.

Partial playlist failure

This is usually expected. VDL isolates failures so other items can continue.

To inspect failures:

vdl playlist "URL" --json

Retry failed items after checking the error category. If failures are subtitle-related, retry without subtitles.

Crawl Issues

Use the interactive app if you want to manually choose which discovered links to crawl or download.

For headless CLI usage, prefer limiting downloads with first-successful behavior if available, for example:

vdl crawl "URL" --first 5

Crawl downloads tiny or unwanted files

Use the minimum file size controls if available in your version, or use interactive/manual selection to choose candidates before download.

State, Config, and Database

Config paths look wrong

Problem: vdl doctor or prompts show the wrong config/output/state paths.

What to do:

  1. Compare the reported paths with the expected defaults above.

  2. Check whether the app is running under:

  3. a test environment

  4. redirected home directory
  5. packaged runtime with stale config
  6. old config file copied from another machine
  7. For Windows binaries, verify the app is using %APPDATA% and %LOCALAPPDATA%, not Unix-style paths or test temp paths.

No local VDL state database found

This is expected if you have not used interactive mode yet.

The headless CLI is mostly stateless. Interactive mode may create local state for history, retries, and session tracking.

To create interactive state, launch:

vdl

or:

vdl interactive

Cannot open database

Problem: The SQLite database is locked or corrupted.

What to do:

  1. Make sure no other VDL instance is running.
  2. Re-run:
vdl doctor
  1. If needed, move the local state database aside and let VDL recreate it.

macOS / Linux

mv ~/.local/state/vdl/vdl.db ~/.local/state/vdl/vdl.db.bak
vdl doctor

Windows PowerShell

Rename-Item "$env:LOCALAPPDATA\vdl\vdl.db" "vdl.db.bak"
vdl doctor

Do not delete the database first unless you are sure you do not need the history.

Storage full

Problem: Download fails with “No space left on device” or a similar error.

What to do:

  1. Free disk space.
  2. Choose a different output directory.
  3. Run:
vdl doctor
  1. Retry the download.

MCP Issues

Claude Desktop does not show VDL tools

What to do:

  1. Verify the MCP command works:
vdl-mcp --help
  1. Generate or inspect MCP configuration:
vdl mcp setup
  1. Add the generated configuration to Claude Desktop.
  2. Restart Claude Desktop.
  3. Check Claude Desktop logs.

MCP command path is wrong

If Claude Desktop cannot start the MCP server, use the full path to vdl-mcp.

Typical paths:

  • macOS/Linux: ~/.local/bin/vdl-mcp
  • Windows: %USERPROFILE%\.local\bin\vdl-mcp.exe

Cookies Not Working

Problem: Downloads are still blocked even with cookies.

What to do:

  1. Make sure you are logged into the site in the browser you selected.
  2. Try a different browser:
vdl download "URL" --cookies-from-browser chrome
vdl download "URL" --cookies-from-browser firefox
  1. If using a cookies file, export a fresh cookies file and retry:
vdl download "URL" --cookies "/path/to/cookies.txt"
  1. If cookies are expired, re-export them from the browser.

Still Stuck?

Collect these before reporting the issue:

vdl doctor
vdl --version

Also capture:

  • install type: standalone binary, uv tool install, or developer checkout
  • operating system and CPU architecture
  • exact command run
  • exact error text
  • whether the issue happens in headless CLI, interactive app, or MCP
  • exact output directory prompt if the issue is path-related
  • whether ffmpeg and ffprobe are available
  • whether default paths point to a real user directory or a test/temp directory
  • whether the failing URL is a single video, playlist, mix, or crawl page

Logs

Check the log directory reported by vdl doctor.

Typical locations:

  • Windows: %LOCALAPPDATA%\vdl\logs
  • macOS/Linux: ~/.local/state/vdl/logs

See Also