Skip to content

Troubleshooting

Jump to bottom
LucQuebec edited this page Jul 2, 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 the required native dependency (curl-cffi) is not available in the standard Android runtime.

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. Update the bundled binary:

YtDlp.updateYtDlp(context, new YtDlp.UpdateCallback() {
    public void onComplete(String s) { Log.d("YtDlp", "Updated: " + s); }
    public void onError(String e)    { Log.e("YtDlp", "Update failed: " + e); }
});

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