VTT Captions Not Loading - WebVTT Fix Guide

Q: Why are my VTT captions not loading?

The most common causes are a missing WEBVTT header, SRT-style comma timestamps, an unreachable track URL, the wrong MIME type, CORS blocking, or a track element that is not configured correctly.

Q: How do I check whether a VTT file is valid?

Use a WebVTT validator first. A valid file should start with WEBVTT, use dot-based timestamps, separate cue blocks with blank lines, and contain parseable caption text.

Q: What MIME type should a VTT file use?

WebVTT files should be served as text/vtt. If a server returns text/plain, application/octet-stream, or an HTML error page, some browsers and players may refuse to load captions.

When VTT captions do not load, the problem is usually either the WebVTT file itself or the way the browser is fetching it.

The useful move is to separate those two problems quickly. First prove the .vtt file is valid. Then check the HTML track element, file URL, MIME type, CORS headers, and player settings.

Quick answer

Validate the caption file with the WebVTT Validator first. A missing WEBVTT header, comma-based timestamps, malformed cue blocks, or invalid timing can stop captions from rendering.

If validation passes, debug delivery: open the VTT URL directly, confirm it returns 200, check that the response is served as text/vtt, then inspect the HTML track element and CORS headers.

If your source file is SRT, use the SRT to VTT Converter instead of renaming the extension.

File problems to check first

Your VTT file should have:

WEBVTT at the top of the file
dot-based timestamps such as 00:00:01.000
cue blocks separated by blank lines
start times before end times
readable caption text after each timing line
a real .vtt file, not an HTML error page saved with a VTT name

A minimal valid VTT file looks like this:

WEBVTT

00:00:01.000 --> 00:00:03.500
First caption line.

00:00:04.000 --> 00:00:06.000
Second caption line.

If the file contains SRT-style commas, convert it properly. This is wrong for WebVTT:

00:00:01,000 --> 00:00:03,500

WebVTT needs dots:

00:00:01.000 --> 00:00:03.500

For a deeper file-level checklist, use How to validate WebVTT files.

Delivery problems after the file validates

If the file is valid but captions still do not appear, the browser may not be receiving the file correctly.

Track URL returns the wrong response

Open the VTT URL directly in the browser. It should show the VTT text, not a login page, redirect loop, 404 page, CDN error, or compressed download prompt.

If the URL does not open cleanly, fix the path before changing player code.

Server uses the wrong MIME type

VTT files should be served as:

text/vtt

Some browsers reject captions when the server returns text/plain, application/octet-stream, or an HTML error response. If the caption file is hosted on a static site, CDN, storage bucket, or custom backend, check the response headers.

CORS blocks the caption request

If the video page and VTT file live on different domains, the subtitle request can be blocked by CORS. This often happens when the video is on one host and captions are on another CDN or storage bucket.

Use How to fix CORS errors for VTT subtitles when the browser console shows CORS errors or the caption URL works directly but fails inside the player.

HTML track setup is incomplete

The browser needs a usable track element:

<video controls>
  <source src="/video/demo.mp4" type="video/mp4" />
  <track
    src="/captions/demo.en.vtt"
    kind="subtitles"
    srclang="en"
    label="English"
    default
  />
</video>

Check that:

src points to the real VTT file
kind is subtitles or captions
srclang is present and matches the language
label is readable in the player menu
the track is selected or marked default when you expect captions to appear automatically

For broader browser-video troubleshooting, use Why subtitles do not show in HTML5 video.

Step-by-step workflow

Open the WebVTT Validator.
Validate the VTT file.
Fix missing headers, comma timestamps, broken cue blocks, or invalid timing.
Open the VTT URL directly in the browser.
Confirm the response is 200 and served as text/vtt.
Check CORS if the captions are hosted on another domain.
Inspect the HTML track element or player configuration.
Test captions in the same browser where users reported the issue.

This order matters because it keeps file syntax, delivery, and player configuration separate.

Common mistakes

Renaming SRT to VTT

VTT needs a header and dot-based timestamps. Use the SRT to VTT Converter when your source file is SRT.

Debugging the player before checking the file

Validate the VTT file first. It is faster than guessing inside player configuration.

Ignoring the response headers

A valid VTT file can still fail if the server sends the wrong MIME type or an HTML error page.

Forgetting cross-origin rules

Captions can be blocked even when the file opens directly in your browser. Check the console and network tab when the VTT file is hosted on a different origin.

Expecting captions to show without selecting a track

Some players do not show captions by default unless the track has default, the user selects it, or the player API enables it.

Frequently asked questions

Why are my VTT captions not loading?

The most common causes are a missing WEBVTT header, SRT-style comma timestamps, an unreachable track URL, the wrong MIME type, CORS blocking, or a track element that is not configured correctly.

How do I check whether a VTT file is valid?

Use the WebVTT Validator first. A valid file should start with WEBVTT, use dot-based timestamps, separate cue blocks with blank lines, and contain parseable caption text.

What MIME type should a VTT file use?

WebVTT files should be served as text/vtt. If a server returns text/plain, application/octet-stream, or an HTML error page, some browsers and players may refuse to load captions.

Can I rename an SRT file to VTT?

No. SRT uses comma timestamps and does not include the required WEBVTT header. Convert SRT to VTT instead of only changing the file extension.