remotion-dev/remotion · error · Error

No tkhd box found

Error message

No tkhd box found

What it means

metadata-from-iso walks each trak looking for a child meta box; when one is found it calls getTkhdBox(t) to obtain the trackId for tagging the metadata. If a trak that contains a meta box has no tkhd (Track Header Box), it throws because the metadata cannot be associated with a track id. tkhd is mandatory in every trak per ISO-BMFF.

Source

Thrown at packages/media-parser/src/metadata/metadata-from-iso.ts:182

	const meta = moov.children.find(
		(b) => b.type === 'regular-box' && b.boxType === 'meta',
	) as RegularBox | null;
	const udta = moov.children.find(
		(b) => b.type === 'regular-box' && b.boxType === 'udta',
	) as RegularBox | null;
	const metaInUdta = udta?.children.find((b) => {
		return b.type === 'regular-box' && b.boxType === 'meta';
	}) as RegularBox | null;

	const metaInTracks = traks
		.map((t) => {
			const metaBox = t.children.find(
				(child) => child.type === 'regular-box' && child.boxType === 'meta',
			) as RegularBox | null;
			if (metaBox) {
				const tkhd = getTkhdBox(t);
				if (!tkhd) {
					throw new Error('No tkhd box found');
				}

				return parseIsoMetaBox(metaBox, tkhd.trackId);
			}

			return null;
		})
		.filter(truthy);

	return [
		...(meta ? parseIsoMetaBox(meta, null) : []),
		...(metaInUdta ? parseIsoMetaBox(metaInUdta, null) : []),
		...metaInTracks.flat(1),
	];
};

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Re-mux the file to repair box structure (`ffmpeg -i in -c copy out.mp4`).
2. If metadata is optional, request fields without metadata and parse tracks/duration separately.
3. Validate with `ffprobe` before parsing; reject files ffprobe cannot read.
4. Report at https://remotion.dev/report if the file is otherwise valid.

Example fix

// before
const {metadata} = await parseMedia({src: malformed, fields: {metadata: true}});

// after: try without metadata, or repair first
let metadata;
try {
  ({metadata} = await parseMedia({src, fields: {metadata: true}}));
} catch (e) {
  if (e.message === 'No tkhd box found') {
    // re-mux first: ffmpeg -i src -c copy repaired.mp4
    ({metadata} = await parseMedia({src: repaired, fields: {metadata: true}}));
  } else throw e;
}

import {execFileSync} from 'node:child_process';
function passesProbe(path: string): boolean {
  try { execFileSync('ffprobe', ['-v','error', path], {stdio:'pipe'}); return true; } catch { return false; }
}

let metadata;
try {
  ({metadata} = await parseMedia({src, fields: {metadata: true}}));
} catch (e) {
  if (e instanceof Error && e.message === 'No tkhd box found') {
    // omit metadata or re-mux the file
    ({durationInSeconds} = await parseMedia({src, fields: {durationInSeconds: true}}));
  } else throw e;
}

When it happens

Trigger: Requesting metadata fields from an MP4 whose trak has a meta child but is missing the tkhd child — a malformed file. Reached when fields include metadata and the container is ISO-BMFF.

Common situations: Hand-edited or partially written MP4s, files produced by tools that emit meta-in-trak without full trak headers, or truncated downloads where the tkhd was lost.

Related errors

• Weird size for number ${size}
• Expected type indicator to be 0
• Invalid ICC profile size
• Invalid ICC profile signature
• Mvhd box is not found

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