Troubleshooting
| Problem | Solution |
|---|---|
The /umd:... commands do not show up | Restart Claude Code or type /reload-plugins. Check /plugin → Installed and the Errors tab. |
node: command not found | Install Node.js 18+ and make sure node is on your PATH. |
| Adding the marketplace fails | Make sure git is installed. Without a GitHub SSH key, set CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 and try again. |
ffmpeg not found | Run /umd:doctor. After an install through winget or Homebrew, open a new terminal so the PATH is reloaded. You can also point to the binaries with UMD_FFMPEG and UMD_FFPROBE. |
Playwright not found or Chromium is not installed | /umd:doctor fix installs both in ~/.umd/runtime. |
Unknown duration when rendering | Set window.umdDuration (in seconds) in the page, or duration_s in .motion/project.json. |
| The render is not reproducible (REN-01) | A source of randomness escapes virtual time: network data, a server timestamp, WebGPU, a font loaded online. The engine's guide (references/engines/) lists the rules. Drive the scene with window.umdRender(t). |
| 3D is slow or blank in the render | Headless Chromium uses software rendering. Iterate with /umd:render draft and check one frame first with umd still. |
| An install is blocked by the guard | Use the suggested alternative (references/licenses.md). If you accept the risk, add the name to license_policy.allow: that is your decision, Claude does not make it for you. |
/umd:deliver refuses to deliver | A blocker is open, or the render changed since the audit: /umd:fix, then /umd:render and /umd:audit. |
umd sync says "no hit within 250 ms" | The planned sound is missing or too quiet under the music: place the effect on the cue time (umd mix --sfx file.wav@6.5) and check it rises above the music. |
/umd:tokens is empty | Transcripts appear after the first Claude Code session in this folder. If you moved your configuration, set CLAUDE_CONFIG_DIR. |
Privacy and security
The plugin sends no telemetry.
- What it contacts:
- During a render, it serves your files on
127.0.0.1and only contacts the URLs your page loads itself. /umd:doctor fixdownloads Playwright from npm, Chromium from Playwright's servers, and FFmpeg through winget or Homebrew.umd styles getdownloads the chosen prompt from GitHub;umd commonsqueries Wikimedia Commons. No data from your project is sent.
- During a render, it serves your files on
- What it reads:
/umd:tokensreads Claude Code's transcripts on your machine and sends nothing. - Hooks: they run locally and are short enough to read: licence guard, session reminder.
- Reporting a vulnerability: see SECURITY.md.
The plugin helps you spot licence traps; it does not replace a lawyer's advice.