Errors and warnings

vidscroll separates the two clearly. Errors stop the video from working; they’re passed to onError (or the element’s vidscroll-error event), logged, and shown in the loading overlay. Warnings mean the video works but could work better; each is logged to the console once per page.

Errors

Errors that come from the video itself are VidscrollError instances with a code:

Hero.tsx

import { ScrollVideo, VidscrollError } from "vidscroll";

<ScrollVideo
  src="/videos/hero.mp4"
  onError={(error) => {
    if (error instanceof VidscrollError && error.code === "http-error") showFallbackImage();
  }}
/>;

Code	When	What to do
`unsupported-url`	`src` is a YouTube, Vimeo, TikTok, Instagram, Facebook, X, Dailymotion or Twitch page, or an HLS/DASH stream (`.m3u8`, `.mpd`)	Use a direct link to a video file
`http-error`	The server answered with an error status, such as 404	Check the path and that the file is deployed
`not-a-video`	The server answered with an HTML page, usually because the file doesn’t exist and the host serves `index.html` instead	Check the path
`unplayable`	The browser can’t play or seek the file, after trying the optimized copy, the downloaded original and streaming	Prepare the file with `npx vidscroll encode`, which makes a standard MP4

Two plain Errors can also occur, both from incorrect setup:

Message	Cause
`Invalid length “…”`	`length` isn’t a number, `“auto”`, or a value in `px`, `vh`, `svh`, `lvh` or `dvh`. Passed to `onError`.
`Section id already exists: …`	Two sections in one video share an `id`. Thrown when the second is added.

Warnings

Messages start with [vidscroll] and name the video’s URL.

Message begins	Meaning
`… isn’t encoded for scrubbing (keyframes are up to Xs apart); re-encoding it in the browser.`	The file has sparse keyframes and is being fixed in the browser. Prepare it with the CLI to skip this.
`… will scrub slowly: …, and this browser can’t re-encode it (no WebCodecs).`	Sparse keyframes in a browser without WebCodecs. Prepare the file.
`… will scrub slowly: …`	Sparse keyframes with `optimize={false}`. Prepare the file or turn optimization back on.
`Re-encoding … failed (…); using the original.`	The in-browser encoder failed. The original stays on screen.
`Couldn’t read … (network error or CORS). Streaming it directly instead`	The file couldn’t be downloaded, usually missing CORS on another domain. See Videos from other domains.
`… is NMB. Every visitor downloads the whole file before scrolling.`	The file is over 100 MB. Use a shorter or smaller video.
`… is Ns long. Scroll-scrubbed videos work best under ~120s`	The video is over two minutes. Long scroll videos mean very long pages and slow first loads.
`Couldn’t switch to the optimized copy of … ; keeping the original.`	The re-encoded copy couldn’t take over. The original stays.
`This browser couldn’t use the downloaded copy of …; streaming it instead.`	The downloaded file couldn’t be played, so the URL is streamed.
`Unknown easing “…”.`	The easing name isn’t a preset. The video uses `none`.

When keyframes can’t be read at all, “keyframes are up to Xs apart” reads “its keyframe layout couldn’t be read” instead.

Troubleshooting: symptoms and fixes.
Automatic optimization: what the re-encode warnings refer to.

Errors

Warnings

Related