Troubleshooting

Start with pnpm odori doctor and the first reported failure. Use the checks below to narrow a problem before changing the composition.

A video does not appear in Studio

Confirm the entry is named video.tsx and lives under the configured videosDir. A file named video.ts or a React component with another filename is not a video entry.

Run discovery outside Studio:

pnpm odori list --json
pnpm odori graph --json

Check duplicate IDs and module errors in the output. Open the project from its root, where odori.config.ts and package.json live. Restart Studio after correcting configuration.

Chrome or FFmpeg is unavailable

Install Odori's managed binaries and check resolution again:

pnpm odori install
pnpm odori doctor

For an existing browser installation, set chromePath in configuration or ODORI_CHROME in the environment. ffmpegPath can select an existing encoder. On Linux, a present executable can still fail to launch when shared libraries are missing; read the browser's startup error.

A rendered frame is blank

Render a point where content should be settled:

pnpm odori inspect launch --json
pnpm odori frame launch --at 2s --output out/debug.png

Check that the requested time falls inside the scene, the component is mounted, and its opacity or transform reaches a visible state. Inspect image URLs and font loading errors. Do not rely on a timer firing before capture; motion should derive from useFrame().

A font differs between preview and export

Declare the font in the brand's fonts list and use the same family name in typography. Put the file under public/fonts/ and reference it as /fonts/your-font.woff2.

Confirm the declared weight matches the file. A static regular font is not a variable font, and declaring a weight range does not make it one. Check font configuration.

Audio is silent or misplaced

Check these conditions in order:

1. Studio playback is unmuted.
2. The cue's file exists and can be resolved.
3. An Audio element places the cue on the timeline.
4. Its gain is above zero and its start lies inside the video.
5. The export does not use --no-audio or an audio-free format such as GIF.

An Audio element inside a scene uses the scene's start as its offset. A brand cue name must resolve to an asset. Inspect the compiled track and see audio for placement examples.

Tests report small text or off-canvas content

Increase the text size, reduce the amount of copy, or adjust the layout. Review the final frame after scaling. Use data-odori-chrome only for decorative UI and data-odori-bleed only for intentional offscreen content.

These exceptions should document an intentional design decision, not suppress a failed review. See testing and review.

An export fails or runs out of memory

Try fewer browser workers, then inspect the failed job:

pnpm odori export launch --concurrency 1
pnpm odori jobs list

Retry the reported job ID after fixing an environment issue. Start a new export after changing source or inputs, because retry uses the old frozen manifest.

When reporting a bug, include the command, Odori and Node versions, operating system, first error, and a minimal reproduction. Remove secrets from logs and input files.