What each error from a YouTube transcript library means, what triggers it, how to reproduce it, and what to do about it. Each page is named after the exact error string, so you can search for it.
Covered so far: every error class in youtube-transcript-api 1.2.4 (17 concrete error classes: 14 that can be raised and 3 legacy cookie classes that never are, plus two base classes). What yt-dlp prints is added where it was observed. Other tools are welcome by pull request.
| Error | Base class | Status | Page |
|---|---|---|---|
IpBlocked |
RequestBlocked |
Reproduced on 2026-10-17 | IpBlocked |
RequestBlocked |
CouldNotRetrieveTranscript |
Reproduced on 2026-10-19 | RequestBlocked |
TranscriptsDisabled |
CouldNotRetrieveTranscript |
Reproduced on 2026-10-17 (latest attempt 2026-10-19 was blocked) | TranscriptsDisabled |
NoTranscriptFound |
CouldNotRetrieveTranscript |
Reproduced on 2026-10-17 (latest attempt 2026-10-19 was blocked) | NoTranscriptFound |
NotTranslatable |
CouldNotRetrieveTranscript |
Reproduced on 2026-10-17 (latest attempt 2026-10-19 was blocked) | NotTranslatable |
TranslationLanguageNotAvailable |
CouldNotRetrieveTranscript |
Reproduced on 2026-10-17 (latest attempt 2026-10-19 was blocked) | TranslationLanguageNotAvailable |
AgeRestricted |
CouldNotRetrieveTranscript |
Reproduced on 2026-10-17 (latest attempt 2026-10-19 was blocked) | AgeRestricted |
PoTokenRequired |
CouldNotRetrieveTranscript |
Not reproduced yet | PoTokenRequired |
VideoUnavailable |
CouldNotRetrieveTranscript |
Reproduced on 2026-10-17 (latest attempt 2026-10-19 was blocked) | VideoUnavailable |
InvalidVideoId |
CouldNotRetrieveTranscript |
Reproduced on 2026-10-17 (latest attempt 2026-10-19 was blocked) | InvalidVideoId |
VideoUnplayable |
CouldNotRetrieveTranscript |
Reproduced on 2026-10-17 (latest attempt 2026-10-19 was blocked) | VideoUnplayable |
YouTubeRequestFailed |
CouldNotRetrieveTranscript |
Not reproduced yet | YouTubeRequestFailed |
YouTubeDataUnparsable |
CouldNotRetrieveTranscript |
Not reproduced yet | YouTubeDataUnparsable |
FailedToCreateConsentCookie |
CouldNotRetrieveTranscript |
Not reproduced yet | FailedToCreateConsentCookie |
CookieError |
YouTubeTranscriptApiException |
Cannot be triggered in this version (never raised in the source) | CookieError |
CookieInvalid |
CookieError |
Cannot be triggered in this version (never raised in the source) | CookieInvalid |
CookiePathInvalid |
CookieError |
Cannot be triggered in this version (never raised in the source) | CookiePathInvalid |
"Status" says whether the repro still produces that error, and when it was last checked. A repro that depends on one video can stop working when the video changes, which is why every claim carries a date. Details on each page, under "Verification history".
The most common failures (IpBlocked, RequestBlocked) say something about the network the request came from, not about the video. In rough order of effort:
- Wait and retry later with a back-off instead of a tight loop. How long a block lasts varies: on one home IP we saw a block lift after roughly 25 minutes and return soon after requests resumed at about ten a minute, so slow down well below that.
- Run from a different network. A home or office connection is treated differently from a cloud server.
- Send requests through a proxy provider. youtube-transcript-api supports proxy configuration.
- Cache what you fetch and fetch each video once.
- If the video has no captions at all, transcribe the audio with a speech-to-text tool instead.
- Use a hosted transcript service, so the blocked IP is not yours. Several exist, for example Supadata, TranscriptAPI, youtube-transcript.io and GetYouTubeTranscript (run by the maintainers of this repository).
- YouTube's official Data API has a captions endpoint, but it needs OAuth with the
youtube.force-sslscope, and in practice works for captions on videos the authorised account can edit.
verify/verify.py runs the automated repros one at a time, pausing between requests, and stops at the first IP block instead of retrying. It records the date, the network ("home network, India", "GitHub Actions runner") and the library version in data/status.json. A GitHub Actions workflow runs it weekly. Results from a cloud runner are often blocked; that is a result too, and it is recorded as such, not hidden.
Pages and this table are generated from data/errors.yaml and data/status.json by python scripts/build.py. Edit those two files, not the generated pages. A check on every pull request fails if the pages are out of sync.
Corrections are welcome, including from the maintainers of any tool mentioned. See CONTRIBUTING.md. Facts need a source: a line of the tool's source, an output you captured (with date and network), or a link.
A shorter, guide-style version with a retry table and an error-handling snippet is on the maintainers' blog: YouTube Transcript Errors Explained. This repository stays the full reference.
The team behind GetYouTubeTranscript, a hosted transcript API, which is one of the options listed above. This repository describes the tools in general and takes pull requests from anyone. MIT licensed.