{"record":{"id":"6f0fd8bc73531b41","repo":"remotion-dev/remotion","slug":"path-startms-is-out-of-timestamp-order","errorCode":null,"errorMessage":"${path}.startMs is out of timestamp order.","messagePattern":"(.+?)\\.startMs is out of timestamp order\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/studio/src/components/parse-caption-file.ts","lineNumber":83,"sourceCode":"\n\t\tif (\n\t\t\ttypeof caption.confidence === 'number' &&\n\t\t\t(caption.confidence < 0 || caption.confidence > 1)\n\t\t) {\n\t\t\tthrow new Error(`${path}.confidence must be between 0 and 1.`);\n\t\t}\n\n\t\tif (\n\t\t\tcaption.pageBreakAfter !== undefined &&\n\t\t\ttypeof caption.pageBreakAfter !== 'boolean'\n\t\t) {\n\t\t\tthrow new Error(\n\t\t\t\t`${path}.pageBreakAfter must be a boolean when provided.`,\n\t\t\t);\n\t\t}\n\n\t\tif (previousStart !== null && caption.startMs < previousStart) {\n\t\t\tthrow new Error(`${path}.startMs is out of timestamp order.`);\n\t\t}\n\n\t\tpreviousStart = caption.startMs;\n\t}\n\n\treturn parsed as Caption[];\n};\n","sourceCodeStart":65,"sourceCodeEnd":91,"githubUrl":"https://github.com/remotion-dev/remotion/blob/b2f4e34732f3c6c222ea029413e22dc402218cd7/packages/studio/src/components/parse-caption-file.ts#L65-L91","documentation":"parseCaptionFile validates that captions parsed from a caption file (e.g. SRT/VTT style input) have non-decreasing start times. When a caption's startMs is earlier than the startMs of the previous caption, parsing is aborted with this error. Remotion requires strictly ordered timestamps so that captions can be rendered in a predictable sequence.","triggerScenarios":"Calling parseCaptionFile on a caption array/file whose entries are not sorted by startMs; manually constructed Caption arrays passed in out of order; caption files with overlapping or shuffled cues.","commonSituations":"Hand-edited caption files, captions exported from a transcription tool that interleaves speakers, or programmatically built caption lists appended in the wrong order.","solutions":["Sort the captions by startMs before passing them to parseCaptionFile (or fix the source file so cues are chronological).","Verify the caption file itself: open it and confirm each cue's timestamp is >= the previous cue's timestamp.","If merging multiple caption sources, merge-sort them by startMs instead of concatenating.","If the caption genuinely starts earlier (overlapping speech), split or shift the cue so startMs respects the ordering rule."],"exampleFix":"// before\nparseCaptionFile(captions);\n// after\nparseCaptionFile([...captions].sort((a, b) => a.startMs - b.startMs));","handlingStrategy":"validation","validationCode":"const sorted = captions.every((c, i, a) => i === 0 || c.startMs >= a[i - 1].startMs);\nif (!sorted) throw new Error('captions are not in startMs order');","typeGuard":"const isInOrder = (cs: {startMs: number}[]) => cs.every((c, i, a) => i === 0 || c.startMs >= a[i - 1].startMs);","tryCatchPattern":"try {\n  const parsed = parseCaptionFile(file);\n} catch (e) {\n  if (e.message.includes('out of timestamp order')) {\n    captions.sort((a, b) => a.startMs - b.startMs);\n  } else throw e;\n}","preventionTips":["Always sort caption arrays by startMs before parsing.","Validate exported caption files for chronological cue order in CI.","When merging caption sources, merge-sort rather than concatenating.","Beware overlapping cues: adjust startMs so it never decreases."],"tags":["captions","validation","ordering"],"backgroundTag":"invalid-argument-value","analyzedSha":"b2f4e34732f3c6c222ea029413e22dc402218cd7","analyzedAt":"2026-09-09T13:27:51.281Z","contentChangedAt":"2026-09-09T13:27:51.281Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}