remotion-dev/remotion · error · Error

EXT-X-MAP directive must have a URI

Error message

EXT-X-MAP directive must have a URI

What it means

Thrown by parseM3uDirective() at parse-directive.ts:136 when #EXT-X-MAP has attribute text but parseM3uKeyValue() did not produce a URI key. Per RFC 8216 section 4.3.2.5 the URI attribute is REQUIRED on #EXT-X-MAP because it tells the client where to fetch the initialization segment. The parser checks p.URI after parsing the key-value pairs.

Source

Thrown at packages/media-parser/src/containers/m3u/parse-directive.ts:136

	if (directive === '#EXT-X-ALLOW-CACHE') {
		if (!value) {
			throw new Error('#EXT-X-ALLOW-CACHE directive must have a value');
		}

		return {
			type: 'm3u-allow-cache',
			allowsCache: value === 'YES',
		};
	}

	if (directive === '#EXT-X-MAP') {
		if (!value) {
			throw new Error('#EXT-X-MAP directive must have a value');
		}

		const p = parseM3uKeyValue(value);
		if (!p.URI) {
			throw new Error('EXT-X-MAP directive must have a URI');
		}

		return {
			type: 'm3u-map',
			value: p.URI,
		};
	}

	if (directive === '#EXT-X-PROGRAM-DATE-TIME') {
		if (!value) {
			throw new Error('#EXT-X-PROGRAM-DATE-TIME directive must have a value');
		}

		// Store the raw ISO 8601 date-time string without validation.
		// This directive associates media segments with absolute dates but
		// doesn't affect parsing of tracks, dimensions, or other metadata.
		return {
			type: 'm3u-program-date-time',

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Ensure #EXT-X-MAP includes URI="...": #EXT-X-MAP:URI="init.mp4",BYTERANGE="4500@600"
2. Regenerate the playlist with a compliant HLS packager
3. Check the init segment URL is valid and reachable

Example fix

// before
#EXT-X-MAP:BYTERANGE="4500@600"

// after
#EXT-X-MAP:URI="init.mp4",BYTERANGE="4500@600"

// Pre-fetch and check EXT-X-MAP has a URI attribute
const text = await (await fetch(url)).text();
for (const line of text.split('\n')) {
  const trimmed = line.trim();
  if (trimmed.startsWith('#EXT-X-MAP')) {
    if (!/URI=/.test(trimmed)) {
      throw new Error('#EXT-X-MAP is missing the required URI attribute');
    }
  }
}

try {
  await parseMedia({src: url});
} catch (e) {
  if (e instanceof Error && e.message === 'EXT-X-MAP directive must have a URI') {
    // add URI="..." to the EXT-X-MAP directive
  }
  throw e;
}

When it happens

Trigger: A #EXT-X-MAP line that has attributes but omits the URI key — e.g. #EXT-X-MAP:BYTERANGE="4500@600" without URI="...".

Common situations: Encoder or packager bug producing an EXT-X-MAP with only BYTERANGE but no URI; hand-edited playlist where the URI attribute was accidentally deleted; malformed init segment declaration.

Related errors

• #EXT-X-MAP directive must have a value
• EXT-X-VERSION directive must have a value
• EXT-X-MEDIA directive must have a value
• EXT-X-TARGETDURATION directive must have a value
• EXTINF has no value

AI-assisted analysis of remotion-dev/remotion@78fe4bb3fd (2026-08-12). Data as JSON: /api/errors/39beb8b04c20138b. Report an issue: GitHub.