remotion-dev/remotion · error

Expected to be inside segment

Error message

Expected to be inside segment

What it means

A Cluster element was encountered but isInsideSegment is null, meaning the Cluster appears outside any Segment. Matroska requires Clusters to live inside a Segment, so this is a structural error in the file or a state-tracking desync.

Source

Thrown at packages/media-parser/src/containers/webm/segments.ts:85

		if (!statesForProcessing) {
			throw new Error('States for processing are required');
		}

		statesForProcessing.webmState.addSegment({
			start: offset,
			size,
		});
		const newSegment: MainSegment = {
			type: 'Segment',
			minVintWidth: offsetAfterVInt - offsetBeforeVInt,
			value: [],
		};
		return newSegment;
	}

	if (segmentId === matroskaElements.Cluster) {
		if (isInsideSegment === null) {
			throw new Error('Expected to be inside segment');
		}

		if (!statesForProcessing) {
			throw new Error('States for processing are required');
		}

		if (mediaSectionState) {
			mediaSectionState.addMediaSection({
				start: offset,
				size,
			});
		}

		statesForProcessing.webmState.addCluster({
			start: offset,
			size: size + (offsetAfterVInt - offset),
			segment: isInsideSegment.index,
		});

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Re-mux with ffmpeg so the EBML header is followed by a Segment before any Cluster.
2. Re-encode from the original source.
3. Try Mediabunny.

Example fix

// shell: ffmpeg -i broken.webm -c copy fixed.webm
await parseMedia({src: 'fixed.webm'});

try {
  await parseMedia({src: 'in.webm'});
} catch (err) {
  if (err instanceof Error && err.message === 'Expected to be inside segment') {
    throw new Error('Cluster outside Segment; re-mux to normalize structure.', {cause: err});
  }
  throw err;
}

When it happens

Trigger: parseMedia reads a Cluster element ID before any Segment element ID has been seen - e.g. a file whose EBML header is followed directly by a Cluster, a reordered/edited file, or state that lost the Segment entry.

Common situations: Hand-edited or damaged MKV/WebM, files produced by muxers that emit Clusters prematurely, or a seek that reset Segment state.

Related errors

• Expected segment
• Expected cluster
• Could not find sample rate or number of channels
• Expected block segment
• Expected CuePoint

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