When getiplayer stops working, it usually stops for one of a handful of well-known reasons, and most of them take minutes to fix. This guide works through the common get_iplayer errors in the order you should check them: the empty search, the download that produces no file, the sudden breakages after BBC changes, and the stubborn PID. Work down the list, test after each step, and you will almost always find your problem before the end. Keep your exact error message visible as you go, because the wording often points straight at the cause.
Problem 1: Your search finds nothing
This is the most common complaint by a distance. You search for a programme you know exists and get_iplayer reports that no programmes are available. Three causes cover nearly every case.
- Your cache is stale. Searches run against a local index, and an old index misses new programmes. Run
get_iplayer --refreshto rebuild it from the BBC feeds, then search again. This single step fixes most empty searches. - The programme has expired. Programmes stay on iPlayer and Sounds for a limited window, often around 30 days, and then they leave the listings. If a refresh does not reveal it, check the iPlayer website: if it is gone there too, it has had its run and cannot be recorded.
- Your search text does not match. The tool matches programme names as the BBC lists them. Try the exact title, check spelling, or search a shorter, distinctive part of the name. Searching without a
--typefilter first can also reveal that the programme is listed as radio when you expected TV, or the other way round.
Problem 2: The download runs but no file appears
A download that seems to complete, yet leaves no MP4 or M4A in your folder, points at ffmpeg. get_iplayer fetches the programme stream, but ffmpeg is the tool that assembles the finished file. If ffmpeg is missing from your system, or installed somewhere the tool cannot find on the PATH, the final step fails and you are left with nothing usable.
The fix is to make sure ffmpeg is properly installed. On Windows and Mac, the official installers bundle or arrange the helper tools, so reinstalling the latest installer usually repairs a broken setup. On Linux, install ffmpeg through your distribution’s packages. Then run the download again. The conversion step at the end should now produce your file in the output folder.
Problem 3: Everything broke suddenly
If getiplayer worked last week and fails today across many programmes, suspect a BBC-side change. The BBC adjusts its feeds and stream systems from time to time, and older copies of get_iplayer can be left unable to read them. Downloads fail, listings misbehave, and nothing you search for behaves as it did.
The answer is to update. get_iplayer warns you when your copy is out of date, and installing the latest release from the project’s GitHub page brings the tool back in step with the BBC’s current systems. This is the highest-value fix in this whole guide: a large share of “getiplayer is broken” reports end the moment the user updates to the current 3.x release.
Problem 4: A PID will not download
Downloading by --pid feels like it should be foolproof, so a failure here is confusing. Check two things. First, the PID itself: it is the code at the end of the programme’s iPlayer or Sounds web address, and one wrong character sends the tool looking for a programme that does not exist. Copy it directly from the address bar rather than typing it.
Second, expiry applies to PIDs too. A PID identifies a broadcast, but if that broadcast has left iPlayer, there is nothing left to fetch, and the download will fail however carefully you copy the code. Confirm the programme still plays on the website; if it does not, the PID has nothing to point at.
Problem 5: Downloads fail partway or stall
Interrupted downloads are frustrating, and it helps to set expectations: get_iplayer’s support for resuming partial downloads is limited, and a failed television download will usually start again from the beginning rather than continuing where it stopped. On a slow or flaky connection, a big HD file is therefore a risk.
Practical defences are simple. Download at standard definition with --modes hvfsd to shrink the file, or pick the standard radio mode for audio, so each download has less distance to travel. Avoid running several large downloads at once on a weak connection. And if a download fails, run it again rather than hunting for partial files; a clean retry beats a salvaged fragment.
Problem 6: You are not in the UK
This one has no workaround, and it is better to know it plainly. BBC iPlayer streams are geo-restricted to the UK. Searches may behave oddly and downloads will fail when attempted from a non-UK location, because the streams themselves refuse the connection. iPlayer is a UK service, UK viewers need a TV licence to use it, and get_iplayer works within those same boundaries. If you are travelling, your downloads will simply have to wait until you are home.
Problem 7: You recorded the wrong programme
Not every failure is an error message. Sometimes get_iplayer works perfectly and records a programme you did not mean to ask for. This usually traces back to a broad --get search: the name matched a different series, an older episode, or a near-identical title, and the tool faithfully downloaded the matches it found.
The prevention is in the workflow. Search without --get first and read the results. Download by index number when a list holds several candidates, so the choice is yours rather than the search’s. Use --pid when you have a specific broadcast in mind, since a PID points at exactly one programme. And add --type or --channel filters to searches for names that exist in more than one place. A minute of choosing beats an hour of downloading the wrong thing.
A sensible troubleshooting order
When several things seem wrong at once, this sequence finds the fault fastest:
- Run
get_iplayer --refreshand repeat your search. - Check the programme still exists on the iPlayer or Sounds website.
- Update get_iplayer to the latest release if it has been a while.
- Confirm ffmpeg is installed and working.
- Retest with a short, current programme before retrying a long one.
Each step rules out one whole family of causes, and most users are back to recording by step three.
Finally, keep a small note of what fixed your problem when you find it. The same cause tends to visit again, after the next BBC change or the next computer move, and a two-line note in your own words will save you the whole investigation next time.
Conclusion
get_iplayer failures look dramatic and resolve plainly. An empty search is usually a stale cache, an expired programme, or a mismatched name. A missing file is usually ffmpeg. A sudden, general breakage is usually a BBC change that a tool update answers. And a dead PID is usually a typo or an expired broadcast. Work through the checks in order, keep the tool updated, and the getiplayer setup that felt broken an hour ago will be filling your download folder again.
Read next: