remotion-dev/remotion · error · Error

A twoslash code block needs a pragma like 'twoslash include

Error message

A twoslash code block needs a pragma like 'twoslash include [name]'

What it means

Thrown during Shiki/twoslash processing in the docusaurus-plugin when a fenced code block uses the `twoslash` language but has no `include` meta pragma (e.g. `twoslash include [name]`). A bare ```twoslash fence is only valid when it declares an include name under which its source is registered; otherwise the processor does not know how to handle it.

Source

Thrown at packages/docusaurus-plugin/src/shiki.ts:141

		}

		// Do nothing if the node has an attribute to ignore
		if (
			Object.keys(fence.meta).filter((key) =>
				(twoslashSettings.ignoreCodeblocksWithCodefenceMeta || []).includes(
					key,
				),
			).length > 0
		) {
			return;
		}

		let shikiHTML: string;

		if (fence.lang === 'twoslash') {
			// Support 'twoslash' includes
			if (!fence.meta.include || typeof fence.meta.include !== 'string') {
				throw new Error(
					"A twoslash code block needs a pragma like 'twoslash include [name]'",
				);
			}

			addIncludes(includes, fence.meta.include, node.value);
			shikiHTML = twoslashSettings.wrapFragments
				? `<div class="shiki-twoslash-fragment"></div>`
				: '';
		} else if (fence.meta.twoslash && isTwoslashEnabled()) {
			// Twoslash code block — use cached call
			const importedCode = replaceIncludesInCode(includes, node.value);
			try {
				shikiHTML = cachedTwoslashCall(importedCode, fence.lang, highlighter);
			} catch (error) {
				const shouldAlwaysRaise =
					process && process.env && Boolean(process.env.CI);

				if (

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Add the include pragma to the fence info string: ` ```twoslash include mySnippet `.
If you did not mean to declare an include, use a normal ` ```ts ` fence with optional `twoslash` meta instead.
Verify the fence info string is parsed correctly (no stray characters).

Example fix

```twoslash
// before (throws)
```

```twoslash include mySnippet
// after
```

Defensive patterns

Strategy: validation

Validate before calling

const fenceHasInclude = (meta: {include?: unknown}): boolean =>
  typeof meta.include === 'string' && meta.include.length > 0;

Type guard

const isValidTwoslashFence = (fence: {lang: string; meta: {include?: unknown}}): boolean =>
  fence.lang === 'twoslash' && typeof fence.meta.include === 'string';

Prevention

Always add `include [name]` to a ```twoslash fence.
Use ```ts with a `twoslash` meta for plain twoslash samples instead.
Lint fenced code blocks in CI to enforce the include pragma.

When it happens

Trigger: Writing a Markdown fence ` ```twoslash ` without a matching `twoslash include someName` meta string. The check `fence.meta.include` is falsy or not a string, so the error fires.

Common situations: Authoring a docs code sample and forgetting the include pragma; copy-pasting a twoslash fence from a tool that stripped the meta; mis-typing the meta as `includes` or `name`.

Related errors

Could not find an include with the key: '${key}'. There is:

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