What causes "Expected track number segment" in remotion-dev/remotion?

Re-mux with ffmpeg to reconstruct TrackEntries with mandatory fields.

Expected track number segment

Error message

Expected track number segment

What it means

getTrackId finds the TrackNumber child of a TrackEntry and throws if it is absent or not of type TrackNumber. TrackNumber is a mandatory element of every TrackEntry per the Matroska spec, so its absence means the track entry is malformed.

Source

Thrown at packages/media-parser/src/containers/webm/traversal.ts:68

	if (child.type !== 'TrackTimestampScale') {
		throw new Error('Expected TrackTimestampScale');
	}

	return child.value;
};

export const getTrackByNumber = (tracks: TrackEntry[], id: number) => {
	return tracks.find((track) => {
		const trackNumber = getTrackNumber(track);
		return trackNumber?.value === id;
	});
};

export const getTrackId = (track: TrackEntry): number => {
	const trackId = track.value.find((b) => b.type === 'TrackNumber');
	if (!trackId || trackId.type !== 'TrackNumber') {
		throw new Error('Expected track number segment');
	}

	return trackId.value.value;
};

export const getCodecSegment = (track: TrackEntry): CodecIdSegment | null => {
	const codec = track.value.find((b) => b.type === 'CodecID');
	if (!codec || codec.type !== 'CodecID') {
		return null;
	}

	return codec;
};

export const getColourSegment = (track: TrackEntry): ColourSegment | null => {
	const videoSegment = getVideoSegment(track);
	if (!videoSegment) {
		return null;

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Re-mux with ffmpeg to reconstruct TrackEntries with mandatory fields.
Validate the file with ffprobe; if tracks are missing numbers, the file is damaged.
Use a different source.
Try Mediabunny.

Defensive patterns

Strategy: try-catch

Try / catch

try {
  await parseMedia({src: 'in.mkv', fields: {tracks: true, samples: true}});
} catch (err) {
  if (err instanceof Error && /Expected track number segment/.test(err.message)) {
    throw new Error('TrackEntry missing TrackNumber; re-mux the file.', {cause: err});
  }
  throw err;
}

Prevention

Re-mux uploads so every TrackEntry has its mandatory TrackNumber.
Validate tracks with ffprobe before parsing.
Keep a fallback source/parser.

When it happens

Trigger: parseMedia is processing a TrackEntry that lacks a TrackNumber child - e.g. a truncated or corrupt track header, or a non-conformant muxer that wrote TrackEntry without TrackNumber. getTrackId is called when samples need to be dispatched to a track.

Common situations: Corrupt MKV/WebM track headers, partially written files, or binary edits that removed the TrackNumber element.

Related errors

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