Troubleshooting

This guide covers common issues you may encounter while using fetchit and how to resolve them. If your problem persists after trying the suggestions here, please open a GitHub issue with the details described at the bottom of this page.

Getting Help

Before diving into specific error sections below, there are a few quick ways to gather diagnostic information that will help both you and the maintainers identify the problem.

Verbose / Debug Output

The single most useful thing you can do when encountering an error is re-run the command with verbose logging enabled. This prints the exact yt-dlp command being executed, the full stdout and stderr streams, and any internal fetchit state.

CLI

fetchit --verbose https://youtube.com/watch?v=...

# Short form also works
fetchit -v https://youtube.com/watch?v=...

Verbose mode shows the raw yt-dlp output, including HTTP requests, extractor debug information, and error traces. When opening a bug report, always include the full output from a verbose run.

Log Files

fetchit writes logs to a persistent location on your system. These logs persist across sessions and can be inspected even after the terminal has been closed.

Platform	Log location
Linux / macOS	~/.local/share/fetchit/logs/
Windows	%USERPROFILE%\.fetchit\logs\

Each run creates a timestamped log file:

BASH

~/.local/share/fetchit/logs/fetchit-2026-07-21T14-30-00.log

To tail the latest log in real-time during a download:

BASH

# Linux / macOS
tail -f ~/.local/share/fetchit/logs/$(ls -t ~/.local/share/fetchit/logs/ | head -1)

# PowerShell
Get-Content "$env:USERPROFILE.fetchitlogs$(Get-ChildItem "$env:USERPROFILE.fetchitlogs" | Sort-Object LastWriteTime -Descending | Select-Object -First 1 -ExpandProperty Name)" -Wait

Configuration Dump

If you suspect a configuration issue, you can dump the effective settings fetchit is using:

CLI

fetchit config dump

This prints the merged configuration from all sources (system config, user config, CLI flags, environment variables) as JSON.

Environment Diagnostics

Run the diagnostic command to check your environment for common prerequisites:

CLI

fetchit doctor

# Checks performed:
#   ✓ Node.js version >= 18
#   ✓ yt-dlp installed and executable
#   ✓ ffmpeg available (if needed)
#   ✓ Write permissions on download directory
#   ✓ Network connectivity to YouTube
#   ✓ Proxy environment variables

Installation Errors

Permission denied during install (Unix)

If you see EACCES: permission denied when installing fetchit via npm globally:

Do not use sudo npm install -g. Using sudo with npm can lead to permission errors later and is a security risk.
Instead, reinstall npm with a prefix you own, or use a version manager. See npm's official guide.
Recommended: use npx to run fetchit without installing globally:
NPM
```
npx fetchit https://...
```

npm global install fails

Global npm installs can fail for several reasons. The most common fixes:

Outdated npm: npm install -g npm@latest then retry.
Registry issues: If you are behind a corporate proxy or in a region with restricted access, npm installs may time out. Configure a mirror:
NPM
```
npm config set registry https://registry.npmmirror.com
```
Lockfile conflicts: Delete node_modules and package-lock.json from any local fetchit clone, then retry.
Node.js version: fetchit requires Node.js 18 or newer. Check with node --version. Consider using nvm or nvm-windows to manage versions.

Binary not found after install

After installing, running fetchit gives command not found (Unix) or 'fetchit' is not recognized (Windows).

npm global bin not in PATH: Find where npm installs global binaries and add it to your PATH.

BASH

# Find the global bin directory
npm bin -g
# Typically:
#   Linux: ~/.npm-global/bin or /usr/local/bin
#   macOS: /usr/local/bin or ~/.npm-packages/bin
#   Windows: %APPDATA%
pm

Windows (PowerShell): You may need to restart your terminal or reload your profile: powershell -ExecutionPolicy RemoteScope & $PROFILE
Windows (cmd.exe): Restart the command prompt or log out and back in.
Try npx: As a temporary workaround, use npx fetchit which does not require a global install.

"command not found: fetchit"

This typically means the global npm binary directory is not in your PATHenvironment variable.

To fix it permanently:

BASH

# Add this to your ~/.bashrc, ~/.zshrc, or ~/.profile:
export PATH="$(npm bin -g):$PATH"

Then reload: source ~/.zshrc

On Windows, npm's global bin is at %APPDATA%\npm — ensure it is listed in your PATH under System Environment Variables.

Install fails on Node.js 22+

fetchit is tested on Node 18, 20, and 22. If you encounter install failures on Node 22, check that you have the latest npm (npm 10+) which ships with better Node 22 support.

yt-dlp Errors

fetchit delegates all download logic to yt-dlp. Most download-related errors originate from yt-dlp itself. Below are the most common error classes and how to address them.

Update yt-dlp first

This cannot be overstated: the majority of yt-dlp errors are fixed simply by updating. YouTube and other sites change their structure frequently, and yt-dlp's extractors need regular updates to keep working.

BASH

# Update yt-dlp via fetchit's bundled copy
fetchit update

If you installed yt-dlp system-wide, update it directly:

BASH

# pip (recommended for standalone installs)
pip install -U yt-dlp

# Homebrew (macOS)
brew upgrade yt-dlp

# Winget (Windows)
winget upgrade yt-dlp

# Scoop (Windows)
scoop update yt-dlp

# Chocolatey (Windows)
choco upgrade yt-dlp

fetchit bundles its own yt-dlp copy. Running fetchit update updates this bundled copy, not the system yt-dlp. If you also have a system-wide yt-dlp, the two are independent.

yt-dlp update fails

If fetchit update itself fails, here are the likely causes:

Network connectivity:yt-dlp's update downloads from GitHub Releases. If GitHub is blocked in your region, use a VPN or proxy.
Permission denied: The bundled yt-dlp is in ~/.fetchit/bin/. Ensure you have write permission to that directory.
Manual update: Download the latest yt-dlp binary manually from yt-dlp releases and replace the file at ~/.fetchit/bin/yt-dlp (or yt-dlp.exe on Windows).
Checksum mismatch: If the downloaded binary is corrupted, run fetchit doctor to verify checksums, then retry the update.

"Sign in to confirm you're not a bot"

YouTube imposes rate limits on IP addresses that generate a high volume of requests. When triggered, YouTube returns a HTTP Error 429 (Too Many Requests)or the "Sign in to confirm" page.

Fix: Rotate your IP

Use a VPN — Connect to a different geographic region to get a clean IP. This works immediately.
Mobile hotspot — Tethering through your phone gives you a carrier IP, which is almost never rate-limited.
Restart your router — Many ISPs assign dynamic IPs; restarting may give you a new one.
Wait 24–48 hours— YouTube's rate-limit flag on an IP resets automatically. If you cannot change your IP, waiting is the only reliable option.

Fix: Provide browser cookies

Passing authenticated cookies from a logged-in browser session often bypasses rate limits:

CLI

fetchit --cookies-from-browser firefox https://youtube.com/watch?v=...

From inside the TUI, press [B] on the error screen to pick a browser and retry automatically.

Use Firefox on Windows when extracting cookies. Chrome and Edge encrypt their cookies with platform-level keys that yt-dlp cannot always decrypt. Firefox stores cookies in plaintext (SQLite) and works reliably across all platforms.

Prevention: Reduce request rate

If you download many videos in quick succession, consider adding a delay between requests. yt-dlp accepts a --sleep-interval option that fetchit passes through:

CLI

fetchit --ytdl-args "--sleep-interval 30" https://youtube.com/playlist?list=...

This inserts a 30-second pause between each video in a playlist, reducing the likelihood of triggering rate limits.

Private video errors

yt-dlp cannot download private or unlisted videos unless you provide authentication cookies from a YouTube account that has access to the video.

Use --cookies-from-browser with a browser where you are logged into the YouTube account that has access.
Alternatively, export cookies to a file with a browser extension and pass them:
CLI
```
fetchit --cookies cookies.txt https://youtube.com/watch?v=...
```
Note that even with cookies, some private videos may refuse download if the account does not have explicit download permission. This is a server-side restriction that yt-dlp cannot bypass.

Age-restricted content

YouTube requires age verification for certain content. Without authentication, yt-dlp returns an error indicating the video is age-restricted.

The simplest fix is to pass cookies from a logged-in, age-verified account.
If cookie passing does not work, your account may not have age verification set up. Complete YouTube's age verification process (usually requires ID upload or credit card).
On the TUI error screen, press [B] to select a browser and retry with cookies.

Geo-blocked content

Some content is restricted to specific countries. If you see HTTP Error 403 or Video unavailable with a geo-blocking message:

Use a VPN in the allowed country. Ensure the VPN is active before starting the download.
Use a proxy: fetchit --proxy http://proxy-server:8080 ...
Cookies from a local account: If you have a YouTube account registered in the allowed country, pass cookies from that account.
Some geo-blocking checks happen at the CDN level. yt-dlp's --geo-bypass flag attempts to work around these, but results vary:
CLI
```
fetchit --ytdl-args "--geo-bypass" https://...
```

"This video is unavailable"

This generic message can mean several things:

Video was deleted or made private — Verify the URL works in a browser.
Content ID takedown — The video was blocked by a copyright claim. Cannot be downloaded.
Regional restriction— Try a VPN in the video's expected region.
Embedding disabled — Some videos block all third-party access. Cookies may help, but some cannot be downloaded at all.
Transient YouTube error — Retry after a few minutes. YouTube sometimes serves temporary errors that resolve on their own.

"Unsupported URL" / No extractor found

yt-dlp supports hundreds of sites, but not every URL is recognized. If you see "Unsupported URL":

Verify the URL is correct and points to a supported site.
Check the list of supported sites.
For sites that require login, try passing cookies. Some sites serve different content (or no content) to unauthenticated viewers.
Update yt-dlp to the latest version — new sites and extractors are added regularly.

ffmpeg Errors

ffmpeg is required for two operations: merging separate video and audio streams into a single file (e.g., best quality YouTube downloads) and extracting audio (-x).

Missing ffmpeg

If yt-dlp downloads both video and audio streams but cannot merge them, you will see an error like ffmpeg not found or Merging formats is not possible.

Install ffmpeg using your system package manager:

BASH

# macOS (Homebrew)
brew install ffmpeg

# macOS (MacPorts)
sudo port install ffmpeg

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

# Fedora / RHEL
sudo dnf install ffmpeg

# Arch Linux
sudo pacman -S ffmpeg

# Windows (Winget)
winget install ffmpeg

# Windows (Scoop)
scoop install ffmpeg

# Windows (Chocolatey)
choco install ffmpeg

# Windows (manual)
# Download from https://ffmpeg.org/download.html and add bin/ to your PATH

After installing ffmpeg, restart your terminal and run fetchit doctor to verify it is detected. If you installed during an active session, the PATH may not have been refreshed.

"Conversion failed!"

ffmpeg can fail for many reasons. The error text from ffmpeg is usually printed above theConversion failed! line. Common causes:

Corrupt download: The video or audio stream was not downloaded correctly. Re-run the download — if the issue persists, a lower quality may be needed.
Unsupported codec: Your ffmpeg build may not include the required codec. Reinstall ffmpeg with all codecs enabled (e.g., brew install ffmpegwithout --without-libx264).
Outdated ffmpeg: Update ffmpeg to the latest version. Older builds may lack support for newer codecs like AV1 or Opus.
Disk space: ffmpeg needs temporary space when remuxing or transcoding. Ensure you have free disk space.

ffmpeg not found in PATH

Even after installing ffmpeg, yt-dlp may not find it. This happens when ffmpeg is installed but not in the system PATH, or the PATH has not been refreshed.

Verify the installation: ffmpeg -version in a new terminal window.
If the command is not found, locate the ffmpeg binary and add its directory to your PATH environment variable.
On Windows, after installing via winget/scoop/choco, you may need to restart the terminal or reboot for PATH changes to take effect.
As a workaround, you can pass the ffmpeg location directly to yt-dlp through fetchit:
CLI
```
fetchit --ytdl-args "--ffmpeg-location C:\path\to\ffmpeg.exe" https://...
```

ffmpeg merge fails with large files

When merging very large files (4K, 8K, long videos), ffmpeg may run out of memory or the file system may hit size limits:

Use a lower-quality format that does not require merging (e.g., download only the video stream and skip audio).
Ensure the download drive has enough free space — ffmpeg needs roughly 2x the final file size for the merge operation.
On Windows, ensure the file system is NTFS (FAT32 has a 4 GB file size limit). Runfsutil fsinfo volumeinfo C: to check.

Audio extraction fails

When using fetchit -x to extract audio, ffmpeg handles the conversion. Failures are often due to missing audio codecs in your ffmpeg build.

Ensure ffmpeg is compiled with --enable-libmp3lame for MP3 output.
For AAC output, ensure --enable-libfdk-aac or use the built-in AAC encoder.
Try a different output format: --audio-format can be mp3, aac, flac, opus, or vorbis.

Download Errors

Network timeouts

If a download stalls or fails with a timeout error (Connection timed out, Read timed out):

Check your internet connection. Run ping google.com to verify basic connectivity.
YouTube server load: YouTube may be slow in your region. Try a VPN or proxy.
Retry with increased timeout: yt-dlp accepts a socket timeout parameter:
CLI
```
fetchit --ytdl-args "--socket-timeout 60" https://...
```
Firewall / corporate proxy: Some networks block or throttle video streaming. Try on a different network to isolate the issue.
Fragment downloads: For very large files, yt-dlp downloads in fragments. A single fragment timeout can abort the whole download. Increase the retry count:
CLI
```
fetchit --ytdl-args "--retries 10 --fragment-retries 10" https://...
```

Connection refused

Connection refused means the remote server actively rejected the connection. This is usually a network-level issue:

YouTube is blocked in your region/country. Use a VPN to a country where YouTube is accessible.
Corporate firewall is blocking the connection. Check with your IT department or try on a personal network.

DNS resolution failure: Try using a different DNS server:

BASH

# Use Cloudflare DNS
fetchit --ytdl-args "--source-address 1.1.1.1" https://...

IPv6 issues: Some networks have broken IPv6. Force IPv4:
CLI
```
fetchit --ytdl-args "--force-ipv4" https://...
```

SSL certificate errors

SSL errors (SSL: CERTIFICATE_VERIFY_FAILED) indicate that Python/yt-dlp cannot verify the certificate presented by YouTube's servers.

Outdated system certificates:Update your operating system's CA certificates:

BASH

# macOS
brew install ca-certificates

# Ubuntu / Debian
sudo apt update && sudo apt install ca-certificates

# Windows
# Run Windows Update to install latest root certificates

Corporate proxy / MITM: If your organization uses SSL inspection, you may need to configure yt-dlp to use the corporate CA certificate:
CLI
```
fetchit --ytdl-args "--ssl-certificate C:\path\to\corp-ca.crt" https://...
```
Date/time incorrect: SSL certificates rely on accurate system time. Ensure your system clock is synchronized:
BASH
```
# macOS
sudo sntp -sS time.apple.com

# Linux
sudo ntpdate -s time.nist.gov

# Windows
w32tm /resync /force
```
Workaround — disable SSL verification (not recommended):
CLI
```
fetchit --ytdl-args "--no-check-certificate" https://...
```
Disabling certificate verification is a security risk and should only be used as a temporary diagnostic measure. Re-enable it as soon as the underlying issue is resolved.

Disk full / no space left

No space left on device (Unix) or Not enough disk space (Windows) is straightforward: the download drive has run out of space.

Check available space: df -h (Unix) or Get-PSDrive C (PowerShell).
Free up space by deleting temporary files, old downloads, or clearing the recycle bin.
Change the download directory to a drive with more space:

CLI

fetchit --output-dir D:\downloads https://...

yt-dlp also downloads video and audio separately before merging, which requires roughly 2x the final file size in temporary space. Ensure you have enough headroom.

Permission denied (file write)

Permission denied when writing the output file means fetchit does not have write permission on the target directory.

Output directory does not exist: yt-dlp does not create intermediate directories. Ensure the output directory exists:
BASH
```
mkdir -p ~/downloads/videos
fetchit --output-dir ~/downloads/videos https://...
```
Read-only filesystem: Check if the target drive or directory is read-only.
macOS: If downloading to an external drive, ensure it is not formatted as NTFS (macOS cannot write to NTFS without third-party tools).
Linux: Check directory permissions with ls -ld /path/to/dir. The user running fetchit must have write permission.
Windows: Run as administrator if downloading to protected locations like C:\Program Files.

File name too long (Windows)

Windows has a 260-character path limit by default. Videos with long titles can produce file paths that exceed this limit.

Enable long path support (Windows 10/11):
BASH
```
# In PowerShell (as Administrator)
New-ItemProperty -Path "HKLM:SYSTEMCurrentControlSetControlFileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
```
Then restart fetchit. Note that long paths must also be enabled in Group Policy or the application must be manifested to support them (fetchit is).
Use a shorter output template:
CLI
```
fetchit --output "%(id)s.%(ext)s" https://...
```
This uses the video ID instead of the full title.
Download to a short path: Use C:\dl instead of a deeply nested folder.
Custom output template: Truncate the title:
CLI
```
fetchit --output "%(title).100B.%(ext)s" https://...
```
This limits the title to 100 characters.

Download is slow

Higher quality = larger files. Try a lower resolution or use -f best[height<=720].
YouTube rate-limits download speed for unauthenticated clients. Using cookies from a premium account can sometimes improve speed.
Network congestion — try downloading at a different time of day.
Use a wired connection instead of Wi-Fi for more stable throughput.
If downloading from a site other than YouTube, the source server may have bandwidth limits.

Resuming interrupted downloads

yt-dlp supports resuming partial downloads for most sites. If a download is interrupted:

BASH

# Simply re-run the same command — yt-dlp detects partial files and resumes
fetchit https://youtube.com/watch?v=...

If resuming does not work (e.g., the partial file was deleted or the URL has expired), delete the partial file (ending in .part, .ytdl, or similar) and start fresh.

Platform-Specific Issues

Windows

Windows SmartScreen / Windows Defender

When fetchit downloads the yt-dlp binary, Windows SmartScreen or Windows Defender may flag it as suspicious. This is a false positive — yt-dlp is legitimate open-source software.

If SmartScreen blocks the download, click More info then Run anyway.

If Defender quarantines the binary, restore it from quarantine and add an exclusion:

BASH

# Add exclusion for fetchit's binary directory
Add-MpPreference -ExclusionPath "$env:USERPROFILE.fetchitin"

You can also manually download the yt-dlp executable from GitHub Releases and place it in %USERPROFILE%\.fetchit\bin\yt-dlp.exe.

EPERM: operation not permitted

This error usually means Windows Defender is scanning the yt-dlp binary while fetchit is trying to execute it. The scan holds a file lock.

Wait a few seconds and retry — the scan is usually transient.
Kill any stuck processes: taskkill /F /IM yt-dlp.exe from an Administrator prompt.
Add ~/.fetchit/bin to Windows Defender exclusions (see above).
As a last resort, temporarily disable real-time protection (not recommended for long-term use).

PowerShell execution policy

If you installed fetchit via npm and run it from PowerShell, you may encounter:... cannot be loaded because running scripts is disabled on this system.

This is a PowerShell execution policy restriction, not a fetchit issue:

BASH

# Check current policy
Get-ExecutionPolicy

# Set to RemoteSigned (allows local scripts, requires remote scripts to be signed)
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Changing execution policy requires Administrator privileges unless you use -Scope CurrentUser. Using npx to run fetchit avoids this issue entirely.

Long path support (Windows 10/11)

As described in the download errors section, Windows has a 260-character MAX_PATH limitation. Videos with long titles can easily exceed this.

Enable long path support system-wide:

BASH

# Registry method (requires reboot)
reg add "HKLMSYSTEMCurrentControlSetControlFileSystem" /v LongPathsEnabled /t REG_DWORD /d 1 /f

Or use a short output template as a per-command workaround.

Terminal encoding / Unicode issues

Some video titles contain Unicode characters that may display incorrectly in the Windows terminal. Set the terminal to UTF-8:

BASH

# PowerShell
$OutputEncoding = [console]::InputEncoding = [console]::OutputEncoding = [Text.UTF8Encoding]::new()

# cmd.exe
chcp 65001

macOS

Gatekeeper / "App is damaged and can't be opened"

macOS Gatekeeper may block the yt-dlp binary because it is not notarized by Apple. This is expected — yt-dlp is open-source software and does not go through Apple's notarization process.

To run it anyway, remove the quarantine attribute:
BASH
```
xattr -d com.apple.quarantine ~/.fetchit/bin/yt-dlp
```
If you still see Gatekeeper warnings, go to System Settings → Privacy & Security and click Open Anyway next to the blocked message.

Quarantine attributes on downloaded files

macOS automatically sets the com.apple.quarantine extended attribute on files downloaded from the internet. This can cause issues when fetchit tries to execute the yt-dlp binary.

Run fetchit's built-in fix:

CLI

fetchit doctor

# Or manually strip the attribute:
xattr -rd com.apple.quarantine ~/.fetchit/

"Operation not permitted" (macOS sandboxing)

macOS 10.15+ has strict sandboxing. If fetchit cannot access certain directories (Desktop, Documents, Downloads), you may need to grant permissions:

Go to System Settings → Privacy & Security → Files and Folders.
Ensure your terminal app has permission to access the download directory.
Alternatively, download to a directory outside the protected areas, such as ~/Videos or ~/Downloads/fetchit.

ffmpeg not found on Apple Silicon (M1/M2/M3)

If you installed ffmpeg via Homebrew on Apple Silicon, it is installed under /opt/homebrew/bin/ffmpeg, which may not be in your PATH if you are using a shell that does not source the Homebrew environment.

BASH

# Add this to ~/.zshrc or ~/.bash_profile:
eval "$(/opt/homebrew/bin/brew shellenv)"

Linux

Missing shared libraries

The yt-dlp binary is a standalone Python executable, but it may depend on certain shared libraries. If you see errors about missing .so files:

BASH

# Ubuntu / Debian
sudo apt install python3 python3-pip

# Fedora / RHEL
sudo dnf install python3 python3-pip

# Arch Linux
sudo pacman -S python python-pip

glibc compatibility

yt-dlp's binary builds have a minimum glibc version requirement. If you are running a very old Linux distribution (e.g., CentOS 7, Ubuntu 18.04), the bundled yt-dlp may not work.

Check your glibc version: ldd --version | head -1
If your glibc is too old, install yt-dlp via pip instead of using the bundled binary:
BASH
```
pip install yt-dlp
# Then ensure pip-installed yt-dlp is found first in PATH
```
Or use the yt-dlp_linux standalone binary which has broader compatibility.

Snap / Flatpak conflicts

If you installed fetchit via npm but also have a snap or flatpak version of yt-dlp on your system, there may be conflicts.

fetchit bundles its own yt-dlp in ~/.fetchit/bin/ and should use it regardless of system packages.
If you suspect fetchit is picking up the wrong yt-dlp, run:
CLI
```
fetchit --verbose https://... | grep "yt-dlp path"
```
This will show which yt-dlp binary is being used.
Snap packages are sandboxed and may not have access to ~/.fetchit/bin/. If you installed fetchit as a snap, consider using the npm install instead.

Clipboard detection doesn't work (Linux)

Clipboard monitoring only works when stdout is a terminal (not in scripts or piped commands).

Install a clipboard tool:

BASH

# X11 (Xorg)
sudo apt install xclip

# Wayland
sudo apt install wl-clipboard

Network and Proxy Configuration

Using a proxy

fetchit passes the proxy setting directly to yt-dlp. You can configure a proxy for all requests:

CLI

fetchit --proxy http://127.0.0.1:8080 https://...
fetchit --proxy socks5://127.0.0.1:1080 https://...

Supported proxy types: HTTP, HTTPS, SOCKS4, SOCKS5.

Environment variables

yt-dlp respects standard proxy environment variables. Set these if you use a system-wide proxy:

BASH

export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1,.internal.company.com

# Or set them per-command:
HTTP_PROXY=http://proxy:8080 fetchit https://...

Proxy authentication

If your proxy requires authentication, include credentials in the URL:

CLI

fetchit --proxy http://username:password@proxy:8080 https://...

Passing credentials in the URL may leak them in process listings. Consider using environment variables or a .netrc file instead.

Corporate NTLM proxy

NTLM-authenticated proxies (common in corporate environments) require special handling. yt-dlp does not support NTLM directly. Use a local proxy relay like NTLM Authorization Proxy Server or Cntlm to bridge NTLM to a standard HTTP proxy.

DNS over HTTPS

If you are experiencing DNS-based blocking, yt-dlp can be configured to use DNS over HTTPS:

CLI

fetchit --ytdl-args "--dns-cache-disabled --dns-address 1.1.1.1" https://...

Known Issues and Workarounds

TUI does not render correctly

The terminal UI requires a terminal that supports ANSI escape codes and Unicode. If the display is garbled:

Windows: Use Windows Terminal (not cmd.exe or the legacy PowerShell ISE). Ensure Virtual Terminal Processing is enabled (it is by default in Windows Terminal).
tmux/screen users: Ensure your $TERM is set correctly (e.g., tmux-256color or screen-256color).
SSH: Ensure your SSH client supports UTF-8 and 256-color terminals. Use ssh -o SendEnv=LANG=en_US.UTF-8.
Fallback to CLI mode: If the TUI is unusable, use the non-interactive CLI mode:
CLI
```
fetchit --no-tui https://...
```

Playlist downloads are slow

Large playlists can take time because yt-dlp fetches metadata for each video sequentially before downloading.

Use --playlist-start and --playlist-end to limit the range:

CLI

fetchit --playlist-start 1 --playlist-end 10 https://youtube.com/playlist?list=...

Use --flat-playlist to skip metadata extraction for non-downloaded videos:
CLI
```
fetchit --ytdl-args "--flat-playlist" https://youtube.com/playlist?list=...
```
Download only specific videos by index: --playlist-items 1,3,5-7

"HTTP Error 403: Forbidden"

A 403 error can mean several things. Try these in order:

Update yt-dlp (fetchit update)
Pass cookies from a logged-in browser
Use a VPN or proxy (geo-blocking)
Try a different video to confirm it is not video-specific

Downloaded file has no audio or no video

YouTube serves video and audio as separate streams. If you end up with a file that has only video or only audio:

yt-dlp automatically merges them if ffmpeg is installed. If not, you will get two separate files or a file missing one stream.
Install ffmpeg (see ffmpeg section above) and retry.
Alternatively, use -f bestvideo+bestaudio which forces yt-dlp to download and merge both streams.

Config file not being read

fetchit reads configuration from:

~/.fetchit/config.json (user config)
.fetchitrc in the current directory (project config)
Environment variables prefixed with FETCHIT_
CLI flags (highest priority)

If your config file is not being applied, verify the file location and format:

BASH

cat ~/.fetchit/config.json
# Should contain valid JSON, e.g.:
# {
#   "outputDir": "~/downloads",
#   "defaultQuality": "best"
# }

Getting Support

GitHub Issues

If you have tried the solutions above and still need help, please open a new GitHub issue. To help us diagnose the problem quickly, include the following:

Bug report template

BASH

## Description
[Clear description of the problem]

## Steps to Reproduce
1. The exact command you ran
2. Expected behavior
3. Actual behavior

## Environment
- OS: [e.g., Windows 11, macOS 14.5, Ubuntu 24.04]
- fetchit version: [fetchit --version]
- Node.js version: [node --version]
- npm version: [npm --version]
- yt-dlp version: [the output from the verbose log]
- ffmpeg version: [ffmpeg -version, if installed]

## Verbose Output
[Run the command with --verbose and paste the FULL output here]

## Additional Context
- Are you behind a proxy/VPN?
- Is this a new issue or has it always happened?
- Does it affect all videos or just one?
- Screenshots, if applicable

What to include

Always include verbose output. Run the failing command with --verbose and paste the full output. This is the single most helpful piece of information.
The exact URL you are trying to download (you can obfuscate personal identifiers if needed, but keep the video ID intact).
Your operating system and versions of fetchit, Node.js, npm, yt-dlp, and ffmpeg.
Any proxy or VPN you are using — corporate proxies are a common source of issues.
What you already tried — this helps us avoid suggesting things that did not work.

Before opening an issue

Search existing issues — your problem may already have a fix or workaround.
Update everything — run fetchit update, update yt-dlp, and update ffmpeg.
Test with a different video to rule out video-specific issues.
Test with a different network (e.g., mobile hotspot) to rule out network issues.
Run fetchit doctor and include its output in your report.

Community support

In addition to GitHub Issues, you can also:

Check the yt-dlp discussions for download-specific questions (many issues are actually yt-dlp issues, not fetchit issues).
Review the fetchit discussions for usage questions and tips.
See the yt-dlp FAQ for frequently asked questions about the underlying download engine.

PreviousContributing NextFAQ

Was this page helpful?