{"record":{"id":"f038f769863c18d1","repo":"remotion-dev/remotion","slug":"separatevideolayers-expects-an-options-object","errorCode":null,"errorMessage":"separateVideoLayers() expects an options object.","messagePattern":"separateVideoLayers\\(\\) expects an options object\\.","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"packages/video-matting/src/separate-video-layers.ts","lineNumber":157,"sourceCode":"\t\t\ttypeof WritableStream === 'undefined' ||\n\t\t\t!(output.outputWritable instanceof WritableStream)\n\t\t) {\n\t\t\tthrow new TypeError(\n\t\t\t\t`outputs.${layer}.outputWritable must be a WritableStream.`,\n\t\t\t);\n\t\t}\n\n\t\tif (output.outputWritable.locked) {\n\t\t\tthrow new TypeError(\n\t\t\t\t`outputs.${layer}.outputWritable must not already be locked.`,\n\t\t\t);\n\t\t}\n\t}\n};\n\nconst validateOptions = (options: SeparateVideoLayersOptions) => {\n\tif (!options || typeof options !== 'object') {\n\t\tthrow new TypeError('separateVideoLayers() expects an options object.');\n\t}\n\n\tconst isBlob = typeof Blob !== 'undefined' && options.src instanceof Blob;\n\tconst isUrl = options.src instanceof URL;\n\tif (typeof options.src !== 'string' && !isUrl && !isBlob) {\n\t\tthrow new TypeError('src must be a string, URL, or Blob.');\n\t}\n\n\tif (typeof options.src === 'string' && options.src.length === 0) {\n\t\tthrow new TypeError('src must not be an empty string.');\n\t}\n\n\tif (\n\t\toptions.outputs !== undefined &&\n\t\t(!options.outputs ||\n\t\t\ttypeof options.outputs !== 'object' ||\n\t\t\tArray.isArray(options.outputs))\n\t) {","sourceCodeStart":139,"sourceCodeEnd":175,"githubUrl":"https://github.com/remotion-dev/remotion/blob/b2f4e34732f3c6c222ea029413e22dc402218cd7/packages/video-matting/src/separate-video-layers.ts#L139-L175","documentation":"validateOptions is the entry guard for separateVideoLayers(): if the single options argument is missing or not an object (null, undefined, a primitive, an array), the function cannot read src/outputs from it, so a TypeError is thrown instead of failing later mid-separation.","triggerScenarios":"Calling separateVideoLayers() with no arguments; passing null; accidentally passing (src, outputs) positionally; spreading gone wrong so the argument is undefined.","commonSituations":"Migrating from an imagined positional API; destructuring results incorrectly; TypeScript unchecked dynamic calls (awaiting user-supplied config).","solutions":["Call with an object: separateVideoLayers({ src, outputs })","Check the calling code for a missing/spread argument","Add a default parameter or guard at the call site"],"exampleFix":"// before\nawait separateVideoLayers('video.mp4', { base: {...} });\n// after\nawait separateVideoLayers({ src: 'video.mp4', outputs: { base: {...} } });","handlingStrategy":"validation","validationCode":"if (options == null || typeof options !== 'object') throw new TypeError('separateVideoLayers requires an options object');","typeGuard":"const isOptionsObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);","tryCatchPattern":"try { await separateVideoLayers(arg); } catch (e) { if (e instanceof TypeError && e.message.includes('expects an options object')) { /* rebuild options */ } else throw e; }","preventionTips":["Always call with a single object literal argument","Enable TypeScript so argument shape is checked at compile time"],"tags":["api-usage","validation"],"backgroundTag":"missing-required-argument","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"}