{"record":{"id":"8e40ef4ef7292077","repo":"remotion-dev/remotion","slug":"forward-seeking-is-not-allowed-when-the-following","errorCode":null,"errorMessage":"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.","messagePattern":"Forward seeking is not allowed when the following fields are requested from parseMedia\\(\\): (.+?)\\. Seek was from 0x(.+?) to 0x(.+?)\\. Either don't seek forward, or don't request these fields\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/media-parser/src/disallow-forward-seek-if-samples-are-needed.ts","lineNumber":21,"sourceCode":"\nexport const disallowForwardSeekIfSamplesAreNeeded = ({\n\tseekTo,\n\tpreviousPosition,\n\tfields,\n}: {\n\tfields: Partial<AllOptions<ParseMediaFields>>;\n\tseekTo: number;\n\tpreviousPosition: number;\n}) => {\n\tconst fieldsNeedingSamples = Object.entries(fields)\n\t\t.filter(([, value]) => value)\n\t\t.map(([key]) => key)\n\t\t.filter(\n\t\t\t(key) => fieldsNeedSamplesMap[key as keyof AllOptions<ParseMediaFields>],\n\t\t);\n\n\tif (fieldsNeedingSamples.length > 0) {\n\t\tthrow new Error(\n\t\t\t`Forward seeking is not allowed when the following fields are requested from parseMedia(): ${fieldsNeedingSamples.join(\n\t\t\t\t', ',\n\t\t\t)}. Seek was from 0x${previousPosition.toString(16)} to 0x${seekTo.toString(\n\t\t\t\t16,\n\t\t\t)}. Either don't seek forward, or don't request these fields.`,\n\t\t);\n\t}\n};\n","sourceCodeStart":3,"sourceCodeEnd":30,"githubUrl":"https://github.com/remotion-dev/remotion/blob/78fe4bb3fdb5a2cd68724393d63cb223db333fa7/packages/media-parser/src/disallow-forward-seek-if-samples-are-needed.ts#L3-L30","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Drop sample-dependent fields (samples, dimensions, etc.) from the fields option when you need to seek forward.","If you need both samples and a target position, parse without forward seeking and let the parser read sequentially up to the target.","Re-evaluate whether a forward seek is required; prefer backward seeks or sequential reads for sample-collecting parses."],"exampleFix":"// before\nparseMedia({\n  src: '/video.mp4',\n  fields: {duration: true, samples: true},\n  controller,\n});\ncontroller.seek(/* forward offset */);\n\n// after - choose one goal\n// Option A: keep samples, do not seek forward\nparseMedia({src: '/video.mp4', fields: {duration: true, samples: true}});\n// Option B: keep forward seek, drop sample fields\nparseMedia({src: '/video.mp4', fields: {duration: true}});","handlingStrategy":"validation","validationCode":"const sampleFields = ['samples', 'dimensions']; // consult fieldsNeedSamplesMap\nconst wantsSamples = Object.entries(fields).some(([k, v]) => v && sampleFields.includes(k));\nif (!wantsSamples) controller.seek(forwardOffset);","typeGuard":"null","tryCatchPattern":"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; }","preventionTips":["Do not request sample-dependent fields when you intend to seek forward.","Decide upfront between seeking and sample collection.","Read fieldsNeedSamplesMap to know which fields are sample-dependent."],"tags":["seeking","fields","samples","api-misuse"],"backgroundTag":null,"analyzedSha":"78fe4bb3fdb5a2cd68724393d63cb223db333fa7","analyzedAt":"2026-08-12T17:18:50.444Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}