remotion-dev/remotion · error

Forward seeking is not allowed when the following fields are

Error message

Forward seeking is not allowed when the following fields are requested from parseMedia(): ${fieldsNeedingSamples.join(', ')}. Seek was from 0x${previousPosition.toString(16)} to 0x${seekTo.toString(16)}. Either don't seek forward, or don't request these fields.

What it means

Thrown by disallowForwardSeekIfSamplesAreNeeded() when a forward seek is requested while parseMedia is also asked to deliver sample-dependent fields (those listed in fieldsNeedSamplesMap, e.g. samples, dimensions). Forward seeking skips bytes, which would leave holes in the sample data the fields promise, so the library refuses rather than emit partial/garbled output.

Source

Thrown at packages/media-parser/src/disallow-forward-seek-if-samples-are-needed.ts:21

export const disallowForwardSeekIfSamplesAreNeeded = ({
	seekTo,
	previousPosition,
	fields,
}: {
	fields: Partial<AllOptions<ParseMediaFields>>;
	seekTo: number;
	previousPosition: number;
}) => {
	const fieldsNeedingSamples = Object.entries(fields)
		.filter(([, value]) => value)
		.map(([key]) => key)
		.filter(
			(key) => fieldsNeedSamplesMap[key as keyof AllOptions<ParseMediaFields>],
		);

	if (fieldsNeedingSamples.length > 0) {
		throw new Error(
			`Forward seeking is not allowed when the following fields are requested from parseMedia(): ${fieldsNeedingSamples.join(
				', ',
			)}. Seek was from 0x${previousPosition.toString(16)} to 0x${seekTo.toString(
				16,
			)}. Either don't seek forward, or don't request these fields.`,
		);
	}
};

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Drop sample-dependent fields (samples, dimensions, etc.) from the fields option when you need to seek forward.
2. If you need both samples and a target position, parse without forward seeking and let the parser read sequentially up to the target.
3. Re-evaluate whether a forward seek is required; prefer backward seeks or sequential reads for sample-collecting parses.

Example fix

// before
parseMedia({
  src: '/video.mp4',
  fields: {duration: true, samples: true},
  controller,
});
controller.seek(/* forward offset */);

// after - choose one goal
// Option A: keep samples, do not seek forward
parseMedia({src: '/video.mp4', fields: {duration: true, samples: true}});
// Option B: keep forward seek, drop sample fields
parseMedia({src: '/video.mp4', fields: {duration: true}});

const sampleFields = ['samples', 'dimensions']; // consult fieldsNeedSamplesMap
const wantsSamples = Object.entries(fields).some(([k, v]) => v && sampleFields.includes(k));
if (!wantsSamples) controller.seek(forwardOffset);

null

try { controller.seek(offset); } catch (e) { if (e.message.startsWith('Forward seeking is not allowed')) { /* drop sample fields or don't seek */ } else throw e; }

When it happens

Trigger: Calling controller.seek() to a later byte offset while fields include any sample-needing option (samples, keyframes, etc.). Combining a fields object requesting sample data with an initial seek past the start position.

Common situations: Building a scrubber that seeks while also collecting samples for waveform/thumbnail generation. Migrating from a fields-only parse to one that also seeks without dropping sample fields. Custom readers that perform speculative forward reads.

Related errors

• The mediaParserController() was not yet used in a parseMedia
• Only supporting fixed count type in stsz box
• bundle() was called without arguments
• bundle() no longer supports the legacy positional arguments.
• bundle() was called without the `entryPoint` option

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