What causes "Unknown track type: ${trackType}" in remotion-dev/remotion?

Re-mux with ffmpeg, which will normalize or drop unknown track types.

remotion-dev/remotion · error · Error

Unknown track type: ${trackType}

Error message

Unknown track type: ${trackType}

What it means

trackTypeToString maps the TrackType uint to a string; values 1-7 cover video/audio/complex/subtitle/button/control/metadata, and any other value throws. The Matroska spec reserves only those values, so an out-of-range TrackType means a non-conformant or corrupt track entry.

Source

Thrown at packages/media-parser/src/containers/webm/segments/track-entry.ts:34

export const trackTypeToString = (trackType: number): TrackType => {
	switch (trackType) {
		case 1:
			return 'video';
		case 2:
			return 'audio';
		case 3:
			return 'complex';
		case 4:
			return 'subtitle';
		case 5:
			return 'button';
		case 6:
			return 'control';
		case 7:
			return 'metadata';
		default:
			throw new Error(`Unknown track type: ${trackType}`);
	}
};

export type GetTracks = () => TrackEntry[];

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Re-mux with ffmpeg, which will normalize or drop unknown track types.
Use ffprobe to list track types; remove the offending track if possible.
Provide a different source file.
Try Mediabunny.

Example fix

// shell: drop the bad track and re-mux
// ffmpeg -i in.mkv -map 0:v:0 -map 0:a:0 -c copy out.mkv
await parseMedia({src: 'out.mkv', fields: {tracks: true}});

Defensive patterns

Strategy: try-catch

Validate before calling

// Validate track types with ffprobe before parsing.
import {execFileSync} from 'node:child_process';
function knownTrackTypes(file: string): boolean {
  const out = execFileSync('ffprobe', ['-v', 'error', '-show_entries', 'stream=codec_type', '-of', 'csv=p=0', file], {encoding: 'utf8'});
  return out.trim().split('\n').every(t => ['video','audio','subtitle','data','attachment'].includes(t));
}
if (!knownTrackTypes('in.mkv')) throw new Error('source has an unknown track type');

Try / catch

try {
  await parseMedia({src: 'in.mkv', fields: {tracks: true}});
} catch (err) {
  if (err instanceof Error && /Unknown track type/.test(err.message)) {
    throw new Error('Non-standard TrackType value; re-mux or strip the offending track with ffmpeg.', {cause: err});
  }
  throw err;
}

Prevention

Use ffprobe to list codec_type before parsing.
Re-mux and -map only known track types.
Reject files ffprobe cannot fully describe.

When it happens

Trigger: parseMedia reads a TrackEntry whose TrackType element has a value outside 1..7 (e.g. 0 or 8+). This happens with proprietary extensions, bit-flipped TrackType values, or experimental muxers.

Common situations: Files from non-standard tools, corrupted track headers, or a partially overwritten TrackEntry.

Related errors

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