remotion-dev/remotion · error

Unknown Remotion skill

Error message

Unknown Remotion skill: ${JSON.stringify(skill)}

What it means

changeRemotionSkill validates the requested skill name against the known remotionSkillNames list before installing or removing it. If the name does not match any known Remotion skill, this error is thrown so the request fails fast instead of passing an invalid package name to the package manager. The skill name is echoed back as JSON for easy debugging.

Solutions

1. Check the exact skill name against the list returned by the get-remotion-skills-info endpoint and correct the request
2. Upgrade Remotion so the desired skill exists in remotionSkillNames
3. Pass only skill names surfaced by the Studio UI rather than hand-typing them

Example fix

// before
await fetch('/api/install-remotion-skill', {body: JSON.stringify({skill: 'captions ')})
// after
await fetch('/api/install-remotion-skill', {body: JSON.stringify({skill: '@remotion/captions'})})

import {remotionSkillNames} from '@remotion/studio-server'; // or read from skills info API
if (!remotionSkillNames.includes(skill)) {
  throw new Error(`Unknown skill: ${skill}`);
}

const isKnownSkill = (s: string): s is RemotionSkillName =>
  remotionSkillNames.some((name) => name === s);

try {
  await installSkill(skill);
} catch (e) {
  if (e.message.startsWith('Unknown Remotion skill')) {
    // correct the skill name and retry
  }
}

When it happens

Trigger: Calling installRemotionSkillHandler or removeRemotionSkillHandler (the install-remotion-skill API route) with a `skill` value that is not in remotionSkillNames — e.g. a typo, a non-Remotion package name, or a stale skill name from an older Remotion version.

Common situations: A Studio client or automation script requests a skill with a misspelled or outdated name; the Remotion version on disk does not ship the requested skill; a hand-crafted API call passes an arbitrary string.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• is not installed.
• assetPath must be a non-empty public-folder path, or an…
• Cannot paste effects: invalid insertion indices
• Component-owned Element initial props must not override…
• Component-owned Element initial style must be an object

AI-assisted analysis of remotion-dev/remotion@46a3a6bf13 (2026-09-18). Data as JSON: /api/errors/7d4ab4b0db5937e2. Report an issue: GitHub.

Appendix: source

Thrown at packages/studio-server/src/preview-server/routes/install-remotion-skill.ts:27

import {remotionSkillNames} from '../../remotion-skill-names';
import type {ApiHandler} from '../api-types';
import {getPackageManager} from '../get-package-manager';
import {getRemotionSkillsInfo} from './remotion-skills-info';

const changingSkillsInProjects = new Set<string>();

const changeRemotionSkill = async ({
	action,
	remotionRoot,
	input: {skill},
	logLevel,
}: Parameters<
	ApiHandler<InstallRemotionSkillRequest, GetRemotionSkillsInfoResponse>
>[0] & {
	readonly action: 'install' | 'remove';
}): Promise<GetRemotionSkillsInfoResponse> => {
	if (!remotionSkillNames.some((name) => name === skill)) {
		throw new Error(`Unknown Remotion skill: ${JSON.stringify(skill)}`);
	}

	if (changingSkillsInProjects.has(remotionRoot)) {
		throw new Error(
			'A skill is already being installed or removed. Please try again once it finishes.',
		);
	}

	changingSkillsInProjects.add(remotionRoot);
	try {
		const installedSkill = getRemotionSkillsInfo({remotionRoot}).skills.find(
			({name}) => name === skill,
		);
		const removingGlobally =
			action === 'remove' &&
			installedSkill?.installedInProject === false &&
			installedSkill.installedGlobally;
		if (

View on GitHub (pinned to 46a3a6bf13)