{"record":{"id":"3df609ce5b312e59","repo":"remotion-dev/remotion","slug":"unsupported-stsd-version-version-3df609","errorCode":null,"errorMessage":"Unsupported STSD version ${version}","messagePattern":"Unsupported STSD version (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/media-parser/src/containers/iso-base-media/stsd/stsd.ts","lineNumber":28,"sourceCode":"\tsamples: Sample[];\n}\n\nexport const parseStsd = async ({\n\toffset,\n\tsize,\n\titerator,\n\tlogLevel,\n\tcontentLength,\n}: {\n\toffset: number;\n\tsize: number;\n\titerator: BufferIterator;\n\tlogLevel: MediaParserLogLevel;\n\tcontentLength: number;\n}): Promise<StsdBox> => {\n\tconst version = iterator.getUint8();\n\tif (version !== 0) {\n\t\tthrow new Error(`Unsupported STSD version ${version}`);\n\t}\n\n\t// flags, we discard them\n\titerator.discard(3);\n\n\tconst numberOfEntries = iterator.getUint32();\n\n\tconst bytesRemainingInBox = size - (iterator.counter.getOffset() - offset);\n\n\tconst boxes = await parseIsoFormatBoxes({\n\t\tmaxBytes: bytesRemainingInBox,\n\t\tlogLevel,\n\t\titerator,\n\t\tcontentLength,\n\t});\n\n\tif (boxes.length !== numberOfEntries) {\n\t\tthrow new Error(","sourceCodeStart":10,"sourceCodeEnd":46,"githubUrl":"https://github.com/remotion-dev/remotion/blob/78fe4bb3fdb5a2cd68724393d63cb223db333fa7/packages/media-parser/src/containers/iso-base-media/stsd/stsd.ts#L10-L46","documentation":"The STSD (Sample Description) box parser only supports version 0; any other version byte throws. STSD is always version 0 in the ISO/IEC 14496-12 spec, so a non-zero byte is almost always cursor desync from an earlier malformed box rather than a real new version.","triggerScenarios":"parseStsd reads a version byte != 0 at the start of an stsd box. Usually downstream of a size-miscount in a preceding box (e.g. dinf, dref, or stbl siblings) that shifted the cursor.","commonSituations":"Corrupt MP4 files, incomplete fragments, or files where the moov hierarchy (trak/mdia/minf/stbl) is damaged.","solutions":["Validate hierarchy with `mp4box -info input.mp4` to find the broken box.","Re-mux: `ffmpeg -i input.mp4 -c copy -movflags +faststart remuxed.mp4`.","Locate the first thrown error in the parse session — that is the real root cause; the stsd version error is a symptom.","If streaming, ensure the entire moov (or moof+mdat segment) arrived before parsing."],"exampleFix":"// before: earlier box size error desyncs cursor, stsd reads version 0xff\nffmpeg -i corrupt.mp4 -c copy fixed.mp4\n// after: well-formed moov, stsd reads version 0","handlingStrategy":"try-catch","validationCode":"function isValidStsdVersion(v: number): boolean {\n  return v === 0;\n}","typeGuard":"function isStsdVersionZero(v: number): v is 0 {\n  return v === 0;\n}","tryCatchPattern":"try {\n  await parseMedia({src, fields: {dimensions: true}});\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith('Unsupported STSD version')) {\n    // re-mux or investigate upstream box errors\n  } else throw err;\n}","preventionTips":["Re-mux with ffmpeg to normalize the moov hierarchy.","Address earlier parse errors first; stsd version errors are usually downstream.","Validate file structure with mp4box -info."],"tags":["media-parser","isobmff","stsd-box","corrupt-file","mp4"],"backgroundTag":null,"analyzedSha":"78fe4bb3fdb5a2cd68724393d63cb223db333fa7","analyzedAt":"2026-08-12T17:18:50.444Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}