remotion-dev/remotion · error · Error

Expected an mp4 file

Error message

Expected an mp4 file

What it means

Thrown during HLS chunk processing when a segment marked as an initialization header (`chunk.isHeader === true`) is parsed and its underlying container structure type is not `iso-base-media` (MP4/fragmented MP4). The parser expects HLS init segments to be MP4 `ftyp`/`moov` boxes; encountering a different container means the stream format is incompatible.

Source

Thrown at packages/media-parser/src/containers/m3u/process-m3u-chunk.ts:341

											callback: callbackOrFalse,
											parentController: state.controller,
											childController,
											subtractChunks: chunksToSubtract,
											chunkIndex,
										});
									};
								},
					reader: state.readerInterface,
					makeSamplesStartAtZero: false,
					m3uPlaylistContext: {
						mp4HeaderSegment,
						isLastChunkInPlaylist: isLastChunk,
					},
				});

				if (chunk.isHeader) {
					if (data.slowStructure.type !== 'iso-base-media') {
						throw new Error('Expected an mp4 file');
					}

					state.m3u.setMp4HeaderSegment(playlistUrl, data.slowStructure);
				}
			} catch (e) {
				currentPromise.rejector(e as Error);
				throw e;
			}

			forwarded.cleanup();

			if (!isLastChunk) {
				childController.pause();
				currentPromise.resolver(makeContinuationFn());
			}
		}

		currentPromise.resolver(null);

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Verify the HLS init segment (`#EXT-X-MAP:URI=...`) is a valid fragmented MP4 file.
2. If the stream is MPEG-TS-based HLS, check whether `@remotion/media-parser` supports that variant; it currently expects fMP4 init segments.
3. Switch to an MP4/fMP4-based HLS encoding if you control the content.
4. Report the stream at remotion.dev/report if it is a standard fMP4 HLS stream that should work.

try {
  await parseMedia({src: 'https://example.com/stream.m3u8'});
} catch (e) {
  if (e instanceof Error && e.message === 'Expected an mp4 file') {
    console.error(
      'The HLS init segment is not an MP4/fMP4 file. ' +
      'Ensure the stream uses fragmented MP4 segments.'
    );
  }
  throw e;
}

When it happens

Trigger: An HLS playlist whose `#EXT-X-MAP` (init segment) references a non-MP4 file — e.g., a WebM, MPEG-TS, or raw AAC initialization segment — and the chunk's `data.slowStructure.type` resolves to something other than `'iso-base-media'`.

Common situations: HLS streams that use MPEG-TS or fMP4 with non-standard encapsulation. Manifests where the init segment URL points to the wrong file. Misconfigured CDN serving a segment body for what should be an init segment. Non-MP4 HLS variants the media-parser doesn't support.

Related errors

• No moov box found in header segment
• No moov box found
• Stream does not have a resolution
• Expected m3u-text-value
• Expected m3u-playlist with src ${src}

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