remotion-dev/remotion · error · Error

Expected an OPFS-backed output target

Error message

Expected an OPFS-backed output target

What it means

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.

Source

Thrown at packages/video-matting/src/create-video-layer-output.ts:249

				}

				finalized = true;

				if (outputMode === 'writable') {
					return {
						dispose: () => Promise.resolve(),
						getBlob: () =>
							Promise.reject(
								new Error(
									'getBlob() is unavailable when outputWritable is used',
								),
							),
					};
				}

				if (outputMode === 'web-fs') {
					if (webFsTarget === null) {
						throw new Error('Expected an OPFS-backed output target');
					}

					let blobPromise: Promise<Blob> | null = null;

					return {
						dispose: discard,
						getBlob: () => {
							blobPromise ??= (async () => {
								const file = await webFsTarget.getBlob();
								const buffer = await file.arrayBuffer();
								return new Blob([buffer], {type: mimeType});
							})();

							return blobPromise;
						},
					};
				}

View on GitHub (pinned to b2f4e34732)

Solutions

1. Ensure the mediabunny Output is constructed with a WebFS target (OPFS file handle / FileSystemWritableFileStream) when using web-fs mode
2. Verify the OPFS directory/file handle was obtained successfully before creating the output
3. Keep outputMode and the target type in sync — derive one from the other

Example fix

// before
const output = new Output({target: new BufferTarget()});
createVideoLayerOutput({output, outputMode: 'web-fs'});
// after
const output = new Output({target: webFsTarget});
createVideoLayerOutput({output, outputMode: 'web-fs'});

if (outputMode === 'web-fs' && webFsTarget === null) {
  throw new Error('Configure an OPFS target before creating a web-fs layer output');
}

const hasOpfsTarget = (t: unknown): t is FileSystemFileHandle =>
  typeof t !== 'undefined' && t !== null && 'createWritable' in (t as object);

try {
  await layerOutput.finalize();
} catch (e) {
  if ((e as Error).message.includes('OPFS-backed output target')) {
    // recreate output with a proper WebFS/OPFS target
  }
  throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Mediabunny did not return an output buffer.
• Mediabunny remux did not return an output buffer.
• Should not happen
• Unexpected type
• has no bytes

AI-assisted analysis of remotion-dev/remotion@b2f4e34732 (2026-09-09). Data as JSON: /api/errors/ea922cb8764a4c85. Report an issue: GitHub.