Common Errors

Running into errors is frustrating, but most problems have straightforward solutions. This guide covers the errors you're most likely to encounter and how to fix them.

Error Detection in Fetchii

When a download fails, its row turns red and shows a short message, like "Login required" or "Network error". Hover over the row to read what happened. A recovery button stays visible on the row: Retry, or Resolve… when signing in could help.

For the full story, select the download and open the inspector (⌘I or the toolbar button). It explains the error and what to try next, with Retry Download, Copy Error, Report Issue… and View Error Log. The same actions are in the row's right-click menu.

Fetchii recognizes the common causes and words them for you:

Login required, Age restricted and Login may help — the Resolve… button offers sign-in options
Private — the content is private; only the owner can share it with you
Network error, Timeout and Proxy unreachable — connection problems, usually fixed by checking your connection and retrying
Region blocked, Removed, Rate limited, Disk full and more — described below

Errors Fetchii doesn't recognize show "Download failed". The original message from the download engine isn't shown in the list, but Copy Error and View Error Log give you the full technical text.

Download Errors

"Removed"

This usually means the video doesn't exist anymore — it was deleted, made private, or the URL is wrong. A link that doesn't point to a video at all shows "No video" or "Unsupported".

Start by checking the URL. Copy-paste errors happen, and a single missing character can break things. Open the link in your browser to see if the video actually plays there. If it works in your browser but not in Fetchii, something else is going on. If it doesn't work anywhere, the video is genuinely unavailable.

The video exists, but you need to be logged in to watch it. This happens with private videos, members-only content, and age-restricted material.

The fix is to give Fetchii access to your login session. The easiest way is through the browser extension — visit the video while logged in, right-click and select Download with Fetchii, and your cookies are sent automatically with the request. For a download that already failed, click Resolve… on its row and choose Retry with Extension, or retry with your Firefox or Chrome cookies from the same sheet.

For detailed instructions, see our Cookie Authentication guide.

"Region blocked"

The video is blocked in your country or region. This is determined by your IP address, and no amount of logging in will help — the content simply isn't available where you are.

A proxy or VPN with a server in an allowed region can bypass this. Configure your proxy in Settings → Network → Proxy, or use a VPN that routes all your traffic through another country. Keep in mind that geo-restrictions often exist for licensing reasons, so consider whether circumventing them is appropriate.

"Age restricted"

Similar to login required, but specifically about age verification. The site requires proof that you're old enough to view the content.

Complete the age verification on the site itself (in your browser), then click Resolve… and retry with the extension or your browser's cookies. The verification status travels with your login session, so once verified, you should be able to download.

Not the Quality You Expected

Not every video is available in every resolution. Fetchii's quality choices are limits — "Up to 1080p" picks the best version up to 1080p — so a download still works when the exact quality doesn't exist; you just get the best one available.

Choose Best Available to always get the highest quality that exists, or click Browse Formats in the New Download sheet (File → New Download…, ⌘N, or the options button in the link field) to see exactly which formats a video offers before downloading.

"Rate limited"

You've made too many requests to the server in a short time, and it's temporarily blocking you. This is the site protecting itself from automated abuse.

The solution is patience. Wait 5-10 minutes and try again. If it keeps happening, lower Max concurrent downloads in Settings → Downloads → Location & Queue — downloading fewer videos simultaneously puts less stress on the server. Switching IP addresses (via proxy) can also help, though some sites track more than just IP.

Network Errors

"Timeout"

The server didn't respond in time. Maybe your internet is slow, the server is overloaded, or there's a routing issue between you and the content.

First, verify your internet is working — can you load websites normally? If your connection is fine but timeouts persist, increase Connection timeout in Settings → Advanced → Download Engine. The default is 30 seconds; bumping it to 60 seconds helps with slow or distant servers. If a specific site consistently times out, the problem might be on their end — try again later.

"Network error"

Fetchii couldn't connect, or the connection broke off. This covers refused connections, dropped connections and addresses that can't be looked up.

Check if the site works in your browser. If it doesn't, the site might be down. If the browser works but Fetchii doesn't, the site might be blocking download tools. Some sites implement measures to prevent automated downloading. Try again later, or check if the site has any legitimate download options.

If you use a proxy and it can't be reached, the error says "Proxy unreachable" instead. Make sure your proxy app is running and that the address and port in Settings → Network are correct, or turn off the proxy.

"SSL error"

Something went wrong establishing a secure connection. This often comes down to system configuration rather than anything you did wrong.

Make sure your Mac's date and time are correct — SSL certificates are time-sensitive, and an incorrect clock causes validation failures. Also ensure macOS is reasonably up-to-date, as very old systems may not support current security standards. If you're using a proxy, try disabling it temporarily to see if that's the issue.

DNS Problems

When your computer can't figure out what IP address belongs to the domain you're trying to reach, the download fails with "Network error". This is a DNS problem, not a Fetchii problem.

Try changing your DNS servers. In System Settings > Network > DNS, add 8.8.8.8 (Google) or 1.1.1.1 (Cloudflare) as alternatives. You can also flush your DNS cache — open Terminal and run sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder.

File System Errors

"Disk full"

There's not enough space to save the download. Video files, especially in high quality, can be several gigabytes.

Free up disk space, or change Download location in Settings → Downloads → Location & Queue to a drive with more room. Choosing a lower quality also helps if you're tight on space.

"Location not writable"

Fetchii can't write to your chosen download folder. This happens when folder permissions are restrictive, the drive is read-only or no longer connected, or macOS security features block access.

Try downloading to a different folder, like your Downloads or Documents folder. If you specifically need to use a restricted location, check the folder's permissions in Finder (File > Get Info), or grant Fetchii access in System Settings > Privacy & Security > Files and Folders.

"File missing"

The download finished, but its file couldn't be found — for example because it was moved or deleted while Fetchii was finishing up. Retry the download.

You don't need to worry about invalid filenames: Fetchii replaces characters like :, /, * or ? automatically. If names look wrong, check your pattern in Settings → Downloads → File Names & Folders (see Custom File Naming).

Conversion Errors

"Processing error"

The video downloaded, but the step that finishes the file — such as merging video and audio or removing SponsorBlock segments — failed.

Check your disk space, since processing needs room for a second copy of the file, then retry the download. If it fails again on the same video, try a different quality or container format.

"Conversion failed"

Something went wrong while converting a file you downloaded. The converted file's row shows "Conversion failed"; hover over it to see why, and use Remove to clear it.

Check your disk space — conversions need room for both input and output. In Transcode Video, try a different codec: H.264 and H.265 use your Mac's hardware encoder, VP9 encodes in software. If you only need a different file type, Change Container doesn't re-encode and rarely fails. If the source file doesn't play correctly in a video player, the file itself might be corrupted.

Engine Errors

"Engine unavailable"

Fetchii's download engine (the component that actually fetches videos) isn't installed or is still being set up.

Fetchii sets it up automatically on first run; the notice bar under the toolbar shows the progress. Wait for it to finish, then retry. If setup fails, the notice says "Setup Failed" with a Retry button — check your internet connection and try again. If it keeps failing, there might be a firewall blocking the download.

"Engine update available"

Sites frequently change their video delivery methods, and the engine needs updates to keep up. When a new engine is ready, the notice bar shows "Engine update available".

Click Update Now in the notice. Updates are usually small and quick. If a site that used to work suddenly fails with "Extraction failed", an engine update often fixes it.

"Download failed"

This is what Fetchii shows when it can't tell what went wrong — it can happen with unusual video files or due to system issues.

Retry the download — it might work the second time. If it keeps failing on the same video, that video might have something unusual about it. Try a different quality or format. Persistent failures across multiple videos warrant checking for Fetchii updates (Fetchii → Check for Updates…).

Getting Help

If you've tried the solutions above and still have problems, here's how to get effective help:

Gather information. Use Copy Error to get the exact error text, and note the URL you're trying to download (if it's not private), your Fetchii version, and your macOS version.

Check the logs. View Error Log opens Diagnostics at the entry for that failure. You can also open it any time from Settings → Privacy → Diagnostics → Open Diagnostics…. Error messages in logs often contain more detail than what appears in the app.

Search first. Many issues have been encountered and solved before. A quick search might find your answer immediately.

Be specific. Report the problem with Report Issue… on the failed download, or Help → Report a Problem…. Include what you tried, what happened, and what you expected. "It doesn't work" is hard to troubleshoot; "I get error X when trying to download from site Y using these settings" is much more actionable.