Skip to content

Troubleshooting

Jump to bottom
LucQuebec edited this page Jul 4, 2026 · 2 revisions

Troubleshooting

Impersonation error

The extractor is attempting impersonation, but no impersonate target is available.
See https://github.com/yt-dlp/yt-dlp#impersonation for information on installing the required dependencies

What it means: yt-dlp needs to impersonate a browser's TLS fingerprint to access this site, but curl-cffi (the Python package that enables this) is not bundled in the free version.

Solutions:

  1. Free version — Use the cookie-based workaround: log the user into the site in a WebView, export the session cookies, and pass them via --cookies.

  2. Pro version — The Pro version bundles curl-cffi compiled for Android (arm64-v8a), solving this permanently without cookies.

HTTP 403 / Access Denied

Possible causes and fixes:

Cause Fix
Session cookies expired Re-export cookies after logging in again
Missing Referer header request.addOption("--add-header", "Referer:https://example.com/")
Site requires impersonation Use the Pro version
IP blocked Use a proxy: request.addOption("--proxy", "socks5://...")

YtDlpException: YtDlp not initialized

You called YtDlp.execute() or YtDlp.executeAsync() before YtDlp.init().

// Always initialize first, once, before any download
YtDlp.init(context);

Download hangs / no progress callback

The progress callback is only called when yt-dlp outputs progress lines. Some format combinations (e.g., audio-only with --extract-audio) may produce fewer progress updates.

Add --newline to force progress on new lines:

request.addOption("--newline");

Output file not found after successful download

The %(title)s template uses the video title, which may contain characters forbidden in file paths on Android. Use a safer template:

request.setOutputTemplate(outputDir + "/%(id)s.%(ext)s");

Or sanitize the title:

request.addOption("--restrict-filenames");  // replaces special chars with underscores

No space left on device

yt-dlp writes a temporary file during download. Ensure your output directory has enough free space, especially for high-quality formats that merge video+audio streams.

Playlist downloads video content instead of audio

Explicitly request audio format:

request.addOption("-f", "bestaudio")
       .addOption("--extract-audio")
       .addOption("--audio-format", "mp3");

Wrong video quality selected

Use -f to specify a format explicitly. To see available formats first (dry run):

request.addOption("-F");  // Lists formats, does not download
YtDlpResponse response = YtDlp.execute(request, null);
Log.d("YtDlp", response.getOutput());  // Prints format table

Then select the format code:

request.addOption("-f", "137+140");  // 1080p video (137) + audio (140)

yt-dlp version is outdated

Sites update their APIs and yt-dlp must keep pace. Because yt-dlp is bundled as Python bytecode inside the AAR at build time, in-app updates are not supported — YtDlp.updateYtDlp() always returns an error.

Fix: bump the library version in your build.gradle to pick up a newer bundled yt-dlp:

implementation 'dev.ffmpegkit-maintained:yt-dlp-android:NEW_VERSION'

Still stuck?

Open an issue on the GitHub repository with:

  • The URL you're trying to download (or the error message if the URL is private)
  • The full exception stack trace
  • Your Android API level and device ABI (arm64-v8a, armeabi-v7a, x86_64)

Clone this wiki locally