{"record":{"id":"ea922cb8764a4c85","repo":"remotion-dev/remotion","slug":"expected-an-opfs-backed-output-target","errorCode":null,"errorMessage":"Expected an OPFS-backed output target","messagePattern":"Expected an OPFS-backed output target","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/video-matting/src/create-video-layer-output.ts","lineNumber":249,"sourceCode":"\t\t\t\t}\n\n\t\t\t\tfinalized = true;\n\n\t\t\t\tif (outputMode === 'writable') {\n\t\t\t\t\treturn {\n\t\t\t\t\t\tdispose: () => Promise.resolve(),\n\t\t\t\t\t\tgetBlob: () =>\n\t\t\t\t\t\t\tPromise.reject(\n\t\t\t\t\t\t\t\tnew Error(\n\t\t\t\t\t\t\t\t\t'getBlob() is unavailable when outputWritable is used',\n\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\t),\n\t\t\t\t\t};\n\t\t\t\t}\n\n\t\t\t\tif (outputMode === 'web-fs') {\n\t\t\t\t\tif (webFsTarget === null) {\n\t\t\t\t\t\tthrow new Error('Expected an OPFS-backed output target');\n\t\t\t\t\t}\n\n\t\t\t\t\tlet blobPromise: Promise<Blob> | null = null;\n\n\t\t\t\t\treturn {\n\t\t\t\t\t\tdispose: discard,\n\t\t\t\t\t\tgetBlob: () => {\n\t\t\t\t\t\t\tblobPromise ??= (async () => {\n\t\t\t\t\t\t\t\tconst file = await webFsTarget.getBlob();\n\t\t\t\t\t\t\t\tconst buffer = await file.arrayBuffer();\n\t\t\t\t\t\t\t\treturn new Blob([buffer], {type: mimeType});\n\t\t\t\t\t\t\t})();\n\n\t\t\t\t\t\t\treturn blobPromise;\n\t\t\t\t\t\t},\n\t\t\t\t\t};\n\t\t\t\t}\n","sourceCodeStart":231,"sourceCodeEnd":267,"githubUrl":"https://github.com/remotion-dev/remotion/blob/b2f4e34732f3c6c222ea029413e22dc402218cd7/packages/video-matting/src/create-video-layer-output.ts#L231-L267","documentation":"Thrown in finalize() when the wrapper resolved outputMode === 'web-fs' but the stored webFsTarget is null, meaning the mediabunny output is not backed by an OPFS (FileSystemWritableFileStream) target as expected. This is an internal consistency check that the configured WebFS target was actually attached to the output.","triggerScenarios":"Creating a video layer output with outputMode 'web-fs' but the underlying mediabunny Output was configured with a different target (e.g. BufferTarget or StreamTarget), so webFsTarget never got set.","commonSituations":"Mismatch between the mode flag passed to createVideoLayerOutput and the target actually constructed; refactors that changed the target but not the mode; bugs where the OPFS file handle failed to open and the code fell back silently.","solutions":["Ensure the mediabunny Output is constructed with a WebFS target (OPFS file handle / FileSystemWritableFileStream) when using web-fs mode","Verify the OPFS directory/file handle was obtained successfully before creating the output","Keep outputMode and the target type in sync — derive one from the other"],"exampleFix":"// before\nconst output = new Output({target: new BufferTarget()});\ncreateVideoLayerOutput({output, outputMode: 'web-fs'});\n// after\nconst output = new Output({target: webFsTarget});\ncreateVideoLayerOutput({output, outputMode: 'web-fs'});","handlingStrategy":"type-guard","validationCode":"if (outputMode === 'web-fs' && webFsTarget === null) {\n  throw new Error('Configure an OPFS target before creating a web-fs layer output');\n}\n","typeGuard":"const hasOpfsTarget = (t: unknown): t is FileSystemFileHandle =>\n  typeof t !== 'undefined' && t !== null && 'createWritable' in (t as object);\n","tryCatchPattern":"try {\n  await layerOutput.finalize();\n} catch (e) {\n  if ((e as Error).message.includes('OPFS-backed output target')) {\n    // recreate output with a proper WebFS/OPFS target\n  }\n  throw e;\n}\n","preventionTips":["Always pair outputMode with the matching mediabunny target type","Obtain and validate the OPFS file handle before creating the output","Add an integration test for each output mode"],"tags":["opfs","web-fs","internal-invariant","mediabunny"],"backgroundTag":"internal-invariant-violation","analyzedSha":"b2f4e34732f3c6c222ea029413e22dc402218cd7","analyzedAt":"2026-09-09T13:27:51.281Z","contentChangedAt":"2026-09-09T13:27:51.281Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}