ytdlp-errors

Classify yt-dlp stderr into a closed taxonomy of error kinds. Zero dependencies, pure regex, ESM + CJS, snapshot-tested against upstream yt-dlp source.

pnpm add ytdlp-errors
# npm install ytdlp-errors  |  yarn add ytdlp-errors  |  bun add ytdlp-errors

Node ≥ 18. ESM + CJS dual export.

• Quick start
• Why this exists
• Error kinds
• API
  • Extension hook
• Adapter recipes
  • yt-dlp-wrap
  • youtube-dl-exec
  • ytdlp-nodejs
• Handling unknown
• Stability contract
• Upstream sync
• Development
• License

Quick start

import { classifyYtDlpStderr, errorKindMetadata } from 'ytdlp-errors';

const { kind, raw } = classifyYtDlpStderr(stderrBlob);
// kind: 'botBlock' | 'ipBlock' | 'rateLimit' | 'geoBlocked' | ...

if (kind !== 'unknown') {
  const meta = errorKindMetadata(kind);
  console.log(meta.code);           // 'YTDLP_BOT_BLOCK'
  console.log(meta.suggestedFlags); // ['--cookies-from-browser', '--cookies']
  console.log(meta.recoverable);    // true
  console.log(meta.userActionable); // true
}

Why this exists

Every JS/TS wrapper around yt-dlp (yt-dlp-wrap, youtube-dl-exec, ytdlp-nodejs, ...) hands you raw stderr and expects you to figure out whether it's a bot block, a geo block, or a disk-full error. yt-dlp emits no structured error channel — its own README recommends Python users embed the library directly; CLI consumers are left parsing text.

This package fills the gap: a curated regex taxonomy of every error kind yt-dlp can produce, audited against the upstream source on every release, with stable codes and metadata that drive UX without locking you to any particular wrapper.

Error kinds

| Kind | Code | Recoverable? | User-actionable? | Typical cause | |---|---|---|---|---| | botBlock | YTDLP_BOT_BLOCK | yes | yes | YouTube anti-bot challenge | | ipBlock | YTDLP_IP_BLOCK | yes | yes | IP-level ban from extractor host | | rateLimit | YTDLP_RATE_LIMIT | yes | yes | HTTP 429 or extractor throttle | | ageRestricted | YTDLP_AGE_RESTRICTED | yes | yes | Login required to confirm age | | unavailable | YTDLP_UNAVAILABLE | no | no | Removed / private / format gone | | geoBlocked | YTDLP_GEO_BLOCKED | yes | yes | Region restriction | | drmProtected | YTDLP_DRM_PROTECTED | no | no | DRM (Widevine/PlayReady) | | loginRequired | YTDLP_LOGIN_REQUIRED | yes | yes | Subscriber-only / private | | outOfDiskSpace | YTDLP_OUT_OF_DISK_SPACE | yes | yes | ENOSPC during write/merge | | chunkTransferFailure | YTDLP_CHUNK_TRANSFER_FAILURE | yes | no | Ranged HTTP truncation; retries exhausted | | missingDependency | YTDLP_MISSING_DEPENDENCY | yes | yes | Required binary such as ffmpeg is missing | | postprocessFailure | YTDLP_POSTPROCESS_FAILURE | yes | no | ffmpeg mux/convert/remux failure | | parse | YTDLP_PARSE_FAILURE | no | no | --dump-json output unparseable | | network | YTDLP_NETWORK | yes | no | Transport-level error | | unsupportedUrl† | YTDLP_UNSUPPORTED_URL | no | yes | URL not handled by any extractor | | unknown | YTDLP_UNKNOWN | no | no | No pattern matched; render raw |

† unsupportedUrl is caller-supplied — not emitted by the stderr classifier. It exists in the union so exhaustive switches cover URL validation before yt-dlp is spawned.

API

| Export | Purpose | |---|---| | classifyYtDlpStderr(stderr, opts?) | Classify a stderr blob. Returns { kind, raw }. | | classifyAll(stderr, opts?) | Classify each ERROR: line independently — use with --ignore-errors on playlists. | | extractLastError(stderr) | Pull the most useful single-line description for logs. Returns string \| null. | | isPostprocessFailure(raw) | Predicate for ENOSPC-masquerading-as-ffmpeg detection. | | errorKindMetadata(kind) | Stable code + recoverability + suggested flags + docs URL. | | YT_DLP_ERROR_KINDS | Closed enum tuple. | | YtDlpErrorKind | Union type. | | ERROR_KIND_METADATA | Full metadata table. | | ERROR_PATTERNS | Internal regex table (not stable — exposed for debugging only). |

Extension hook

For site-specific patterns that don't belong upstream:

classifyYtDlpStderr(stderr, {
  extraPatterns: {
    ipBlock: /custom-site-ban-string/i,
    rateLimit: [/throttled by upstream/i, /retry-after exceeded/i]
  }
});

Custom patterns run before built-ins. Keys must be existing ClassifierKind values — to add a new category, open a PR.

Adapter recipes

yt-dlp-wrap

import YTDlpWrap from 'yt-dlp-wrap';
import { classifyYtDlpStderr, extractLastError } from 'ytdlp-errors';

const ytdlp = new YTDlpWrap();
const proc = ytdlp.exec(['-f', 'best', url]);
let stderr = '';
proc.on('error', (err) => { stderr += String(err); });
proc.on('close', () => {
  const { kind } = classifyYtDlpStderr(stderr);
  if (kind !== 'unknown') console.error('classified:', kind);
  else console.error('raw:', extractLastError(stderr));
});

youtube-dl-exec

import ytdl from 'youtube-dl-exec';
import { classifyYtDlpStderr } from 'ytdlp-errors';

try {
  await ytdl(url, { format: 'best' });
} catch (err) {
  const { kind, raw } = classifyYtDlpStderr(err.stderr ?? String(err));
  console.error(kind, raw);
}

ytdlp-nodejs

import { YtDlp } from 'ytdlp-nodejs';
import { classifyYtDlpStderr } from 'ytdlp-errors';

const ytdlp = new YtDlp();
const stream = ytdlp.stream(url);
let stderr = '';
stream.on('error', (chunk) => { stderr += chunk; });
stream.on('end', () => {
  if (stderr) console.error(classifyYtDlpStderr(stderr).kind);
});

Handling unknown

classifyYtDlpStderr never throws. When no pattern matches, you get { kind: 'unknown', raw }. Surface raw verbatim — the upstream snapshot scan opens a PR when new unrecognized strings appear, so unknowns shrink over time.

Stability contract

• code strings are public API. Host apps key i18n strings, analytics labels, and logs on them. Golden-tested in tests/codes-golden.test.ts. Changing a code is a major SemVer bump.
• YtDlpErrorKind is a closed enum. Adding a kind is a minor bump; consumers' exhaustive switches will warn. Removing a kind is a major bump.
• Regex internals are not public API. src/patterns.ts and ERROR_PATTERNS are internal. Tweaks that don't change classification outcomes for known strings ship as patch.
• Upstream snapshot drives audit. data/known-yt-dlp-strings.json (auto-generated) and data/known-extractor-strings.json (curated) pin the lib to specific yt-dlp source strings. CI fails if a snapshot entry's declared kind stops classifying correctly.

Upstream sync

scripts/scan-yt-dlp-source.mjs clones yt-dlp at the pin in data/yt-dlp-version.json, greps for report_error / raise *Error / raise_* call sites, dedupes by content hash, and writes data/known-yt-dlp-strings.json. Each entry carries source (file:line), call (which API emitted it), fragment (the string), and kind (null until triaged).

A weekly CI cron re-runs the scan, bumps the pin to the latest stable yt-dlp release, and opens a PR. Reviewers triage kind: null entries.

Coverage tests (tests/upstream-coverage.test.ts) assert every non-null entry round-trips through classifyYtDlpStderr to its declared kind. Fixture blobs in tests/fixtures/yt-dlp-stderr/ provide realistic full-stderr samples per kind.

Development

pnpm test          # run tests with vitest
pnpm typecheck     # type-check without emitting
pnpm build         # compile to dist/
pnpm run scan-upstream  # re-scan upstream yt-dlp source

License

MIT © Antonio Orionus