remotion-dev/remotion · error · Error

Could not find an include with the key

Error message

Could not find an include with the key: '${key}'.
There is: ${Array.from(_map.keys())}.

What it means

Thrown by `replaceIncludesInCode` in the docusaurus-plugin when a `// @include: someKey` marker in a docs code block references a key that is not present in the includes Map. The error lists the available keys so the author can correct the reference. Includes are registered earlier via `addIncludes` from twoslash or fenced blocks named with `// - name` pragmas.

Solutions

1. Check the available keys printed in the error and fix the typo to match an existing include name.
2. Ensure the include is defined with a `twoslash include [name]` pragma or `// - subkey` marker in a code block processed before the reference.
3. Re-run the docs build to confirm the key resolves.

Example fix

// before
// @include: mispelled-name

// after (match the registered pragma)
// @include: correct-name

const key = 'myInclude';
if (!includeMap.has(key)) {
  throw new Error(`include '${key}' missing; available: ${[...includeMap.keys()]}`);
}

const includeExists = (map: Map<string, string>, key: string): boolean =>
  map.has(key);

When it happens

Trigger: A docs MDX/Markdown code block contains `// @include: foo` but no include named `foo` (or `parentName-foo`) was registered. Typo in the key, a renamed include, or an include defined in a different file that was not added to the shared map.

Common situations: Renaming an include pragma without updating references; referencing an include from a file that is processed later or not at all; copy-pasting an include marker from another doc.

Related errors

• A twoslash code block needs a pragma like 'twoslash include…

AI-assisted analysis of remotion-dev/remotion@78fe4bb3fd (2026-08-12). Data as JSON: /api/errors/66b74779475d3809. Report an issue: GitHub.

Appendix: source

Thrown at packages/docusaurus-plugin/src/includes.ts:47

	// const toReplace: [index:number, length: number, str: string][] = []
	const toReplace = [];

	let match;
	while ((match = includes.exec(code)) !== null) {
		// This is necessary to avoid infinite loops with zero-width matches
		if (match.index === includes.lastIndex) {
			includes.lastIndex++;
		}

		const key = match[1];
		const replaceWith = _map.get(key);

		if (!replaceWith) {
			const msg = `Could not find an include with the key: '${key}'.\nThere is: ${Array.from(
				_map.keys(),
			)}.`;
			throw new Error(msg);
		}

		toReplace.push([match.index, match[0].length, replaceWith]);
	}

	let newCode = code.toString();
	// Go backwards through the found changes so that we can retain index position
	toReplace.reverse().forEach((r) => {
		newCode =
			newCode.substring(0, Number(r[0])) +
			r[2] +
			newCode.substring(Number(r[0]) + Number(r[1]));
	});
	return newCode;
};

View on GitHub (pinned to 78fe4bb3fd)