Troubleshooting

Start with npx @genmotion/cli doctor. It checks Node, ffmpeg, Chromium and WebGL, and prints the fix for anything that fails.

Installing#

"404 Not Found: genmotion" from npm or npx#

The CLI's npm package is @genmotion/cli; it provides the genmotion command. npm refuses the bare name genmotion, so npx genmotion@latest and npm install -g genmotion fail outside a project. Use these instead:

npx @genmotion/cli@latest init my-video      # or: npm create genmotion@latest my-video
npm install -g @genmotion/cli                # the genmotion command, everywhere

Inside a project, after npm install, npx genmotion and the npm run scripts work as before. If an agent is following an older setup prompt, copy the current one from Quickstart.

"Node 22 or newer is required"#

Install a current Node from nodejs.org or with a version manager (nvm install 22), then open a new terminal.

"No Chromium found"#

The first render downloads one automatically. If your network blocks the download, run npx @genmotion/cli browser install on another network, or point GENMOTION_CHROMIUM at an installed Chrome.

"ffmpeg not found"#

ffmpeg is also downloaded on first use. Set FFMPEG_PATH to use your own.

Rendering#

Renders are slow#

Add --gl gpu to use your graphics card, and raise --concurrency on a machine with more cores. The default software WebGL is slow but identical everywhere.

A scene renders blank or black#

Run npx @genmotion/cli check. It flags frames that are a single flat color and says whether the camera is pointing away or the objects are unlit. Then npx @genmotion/cli still --at 50% to see the frame yourself.

The export doesn't match the preview#

A scene is reading a clock or random numbers. npx @genmotion/cli check names the line; replace it with the time, frame or progress the update function receives. See the determinism rules.

"Not inside a GenMotion project"#

Run the command from the project folder (any subfolder works), or pass --dir path/to/project.

Agents#

The MCP server doesn't show up#

• Claude Code: approve the genmotion server when asked, or run claude mcp list. Restart the session after adding it.
• Cursor: enable it under Settings → MCP.
• Any client: the server must start in the project folder, or get --dir. Run npx -y @genmotion/cli mcp in a terminal; it should wait silently for input.

The agent ignores the project's rules#

Make sure it was opened in the project folder, so it can read AGENTS.md or CLAUDE.md. npx @genmotion/cli skills update rewrites those files if they're missing or stale.

GenMotion Studio#

The app can't find Claude Code or Codex#

Install one and sign in once in a terminal (claude or codex), then restart GenMotion.

Two genmotion commands, or a command that's out of date#

Older versions of the Studio wrote a launcher script to /usr/local/bin/genmotion, which can block npm install -g @genmotion/cli or answer ahead of it. npx @genmotion/cli doctor lists every genmotion on your PATH and flags the old script. Run genmotion upgrade, or choose Update the 'genmotion' command in the Studio's account menu, to replace it with the npm command.

HyperFrames projects in the CLI#

The CLI renders Three.js and React projects. Open HyperFrames projects in the Studio.

Errors in HyperFrames and Remotion projects#

If the problem is in the composition rather than in GenMotion, the answers are collected at /answers: HyperFrames (black renders, slow renders, fonts, install) and Remotion (delayRender timeouts, stuck renders, licensing). Two to start with are why a HyperFrames render is black and why a green check can still mean a wrong video.