# youtube-transcript npm Returns an Empty Array: Causes and a Working Fix

Source: https://transcript-yt.com/blog/youtube-transcript-npm-empty-array · Updated 2026-11-17 · TranscriptYT

> Why the youtube-transcript npm package returns [] or fails on servers: YouTube caption changes and blocked cloud IPs. Diagnose it and swap in one fetch call.

The youtube-transcript npm package returns an empty array when YouTube answers its caption request with a body its parser doesn't recognize, usually an empty response or a changed XML format, and it returns [] instead of throwing. The two root causes are YouTube changing how captions are served (which broke versions 1.2.1 and earlier) and YouTube refusing or emptying requests from server and cloud IPs, which no package update can fix. This guide shows how to tell which one you have, and how to replace the call with a single fetch to the [TranscriptYT API](https://transcript-yt.com/api) that keeps the same output shape.

## Why youtube-transcript returns [] instead of an error

In the current release (1.3.1, April 2026), fetchTranscript first asks YouTube's internal player API for the caption track list as an Android client. If that call fails for any reason, the error is swallowed and the package falls back to downloading the watch page and reading ytInitialPlayerResponse from it. Either way it ends up with a caption track URL, downloads it, and parses the XML with two regular expressions: one for the srv3 format (<p t="..." d="...">) and one for the classic format (<text start="..." dur="...">).

If the caption download returns HTTP 200 with an empty body, or with markup neither regex matches, the parser finds nothing and returns an empty array. There is no check for that case, so your code sees a successful call with zero segments. Errors are only thrown for a few specific signals: a reCAPTCHA on the watch page, a missing playabilityStatus, no caption tracks, a missing language, or a non-OK caption response.

## How to tell which problem you have

Version 1.3.x accepts a custom fetch in its config, so you can log every request it makes without patching the package. Run this once on your laptop and once on the server where it fails.

- Check your installed version with npm ls youtube-transcript. Anything at 1.2.1 or below has the old parser.
- Caption request returns 200 with 0 bytes: YouTube served an empty caption file. Common from cloud IPs and from web-client caption URLs fetched without the tokens YouTube's own player sends.
- Caption request returns 200 with a large body but you still get []: the format changed under the parser. Upgrade, or log the first 300 characters of the body to see the markup.
- Watch page body is small or contains a consent or sign-in page: the request was treated as a bot. You'll often see "Transcript is disabled on this video" here even though the video has captions.
- Empty on the server, populated locally with the same video ID: it's the server's IP, not your code.

```
import { YoutubeTranscript } from "youtube-transcript";

const loggingFetch = async (url, init) => {
  const res = await fetch(url, init);
  const body = await res.clone().text();
  console.log(res.status, String(url).slice(0, 70), body.length + " bytes");
  return res;
};

const items = await YoutubeTranscript.fetchTranscript("VIDEO_ID", {
  fetch: loggingFetch,
});
console.log(items.length + " segments");
```

## Old versions broke when YouTube changed the caption format

Version 1.2.1 was published in April 2024 and stayed the latest release until 1.3.0 in March 2026. It split the watch page HTML on the string "captions": to find the track list, then matched only the classic <text start="..." dur="..."> caption format. When YouTube began returning caption files the regex didn't match, or empty bodies, that version had no fallback and returned [] for videos that clearly had captions.

1.3.0 added the Android player API path and the srv3 parser, so upgrading fixes a large share of local failures:

```
npm install youtube-transcript@latest
```

## Works locally, empty on Vercel, AWS Lambda, or a VPS

If upgrading fixed your laptop but production still returns [] or throws YoutubeTranscriptTooManyRequestError, the cause is the network. Vercel and Netlify functions run on AWS, Cloudflare Workers run on Cloudflare's network, and VPS providers own their IP ranges. YouTube treats traffic from these ranges as automated and answers with a captcha, a sign-in check, or caption responses with nothing in them. The same code from a home connection gets real captions.

Because the package hides the first failure and parses whatever comes back, a blocked request can surface as any of three things: an empty array, "Transcript is disabled on this video", or the too-many-requests error. The serverless version of this problem, with route handler examples, is covered in [YouTube transcripts on Vercel, Netlify, and Cloudflare Workers](https://transcript-yt.com/blog/youtube-transcript-vercel-serverless), and the Python equivalent in [RequestBlocked fixes for youtube-transcript-api](https://transcript-yt.com/blog/youtube-transcript-api-request-blocked).

## Forks, proxies, and other workarounds

Forks such as youtube-transcript-plus keep the same approach of calling YouTube's unofficial endpoints, and their own README warns they can break when YouTube changes its internal structure. They help with format changes but not with blocked IPs. The options people try next, and what they cost you:

- Residential proxy passed through the custom fetch option: works, but you pay per GB, need rotation and retries, and maintain it when YouTube changes again.
- Fetching from the browser: YouTube's caption endpoints don't allow cross-origin requests, so the browser blocks the response.
- Running yt-dlp on the server: it hits the same IP checks (see [yt-dlp "Sign in to confirm you're not a bot"](https://transcript-yt.com/blog/yt-dlp-sign-in-to-confirm-not-a-bot)) and adds a binary to your deployment.
- Calling a transcript API: one HTTPS request from your server; the provider handles YouTube's changes and blocks.

## Replace youtube-transcript with one fetch call

This is the request from the [API docs](https://transcript-yt.com/docs), wrapped to return the same { text, offset, duration, lang } objects youtube-transcript returns, so the rest of your code doesn't change. It runs anywhere fetch exists: Node.js 18+, Bun, Deno, Vercel functions, and Workers. Keep the key in an environment variable on the server, never in client code.

Two differences to know. offset and duration are always in seconds here; youtube-transcript 1.3.x returns milliseconds for srv3 captions and seconds for classic ones, so check any code that divides by 1000. And if a video has no track in the language you ask for, TranscriptYT machine-translates the original into it and sets translated: true on the response, where youtube-transcript throws.

```
// transcript.js: same call shape as YoutubeTranscript.fetchTranscript
export async function fetchTranscript(video, { lang } = {}) {
  const params = new URLSearchParams({ url: video, mode: "captions" });
  if (lang) params.set("language", lang);

  const res = await fetch("https://transcript-yt.com/v1/transcript?" + params, {
    headers: { Authorization: "Bearer " + process.env.TRANSCRIPTYT_KEY },
  });
  const body = await res.json();
  if (!res.ok) throw new Error(body.error?.message ?? body.error);

  return body.segments.map((s) => ({
    text: s.text,
    offset: s.start, // seconds
    duration: s.duration, // seconds
    lang: body.language,
  }));
}
```

## Free credits, errors, and videos without captions

A free account gets 100 credits once, with no card. Each successful transcript costs 1 credit, cache hits included, and failed requests are never billed. After that, Micro is $3 a month for 1,000 credits. If you just need one transcript and not code, paste the link into the [free transcript tool](https://transcript-yt.com/youtube-transcript).

Errors come back as { error: { code, message } } with a real HTTP status instead of an empty array, so you can branch on them:

- NO_CAPTIONS (404): the video has no captions. Drop mode=captions to let paid plans and credit packs fall back to AI transcription, billed per minute of audio, for videos up to 2 hours. Free accounts get captions only.
- VIDEO_UNAVAILABLE (404): private, deleted, or region-locked.
- LANGUAGE_NOT_AVAILABLE (404): the requested language isn't offered.
- RATE_LIMITED (429) and BLOCKED (503): retry after the Retry-After header or a short backoff.
- 402: out of credits, with upgrade and top-up links in the body.

## FAQ

### Why does youtube-transcript return an empty array?

YouTube answered the caption request with an empty or unrecognized body, and the package's parser returns [] instead of throwing. Upgrade to 1.3.x for the format change; if it still happens only on your server, YouTube is blocking that IP.

### Why does youtube-transcript work locally but not on Vercel?

Your laptop uses a residential IP and Vercel functions run on AWS IPs, which YouTube treats as bots. The package can't fix that; route the request through a transcript API or a residential proxy.

### Is youtube-transcript offset in seconds or milliseconds?

In 1.3.x it depends on the caption format YouTube returns: milliseconds for srv3 captions, seconds for the classic format. Version 1.2.1 and earlier returned seconds.

### Can I use youtube-transcript in the browser?

No. YouTube's caption endpoints don't allow cross-origin requests, so call it, or a transcript API, from server code and pass the result to the frontend.
