Installation Troubleshooting

This page addresses common installation failures for OpenMontage after following the initial setup steps. All commands assume you are in the project root.

Missing FFmpeg

Many tools (video composition, scene detection, frame sampling) require FFmpeg. If you see "ffmpeg not found" or related errors:

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

# Verify
ffmpeg -version

Ensure the binary is on your PATH. Re-run make setup after installation.

Node.js and npm Errors

OpenMontage requires Node.js 18+. Remotion and HyperFrames components fail without it.

Check your version:

node --version

Install Remotion manually if the automated step failed:

cd remotion-composer && npm install && cd ..

On Windows, if npm install fails with ERR_INVALID_ARG_TYPE:

npx --yes npm install

For HyperFrames cache problems:

npx --yes hyperframes --version

GPU Support Problems

Local video generation requires an NVIDIA GPU and the GPU stack. Run:

make install-gpu

This executes:

pip install -r requirements-gpu.txt
pip install diffusers transformers accelerate

Then enable in .env:

VIDEO_GEN_LOCAL_ENABLED=true
VIDEO_GEN_LOCAL_MODEL=wan2.1-1.3b

Local models need sufficient VRAM (6 GB+ for entry models, 24 GB+ for wan2.1-14b). CPU-only machines fall back to cloud or Remotion paths.

Post-Setup Verification with Make Targets

After make setup (or the manual equivalent), run these targets before any production:

make preflight

This performs capability discovery and prints a summary of available tools, render engines, and setup offers.

For HyperFrames specifically:

make hyperframes-doctor

Additional targets:

• make hyperframes-warm — refreshes the npx cache.
• make clean — removes __pycache__ and .pyc files.

If preflight reports missing providers or runtimes, see the detailed diagnostics in Preflight Diagnostics. For environment variable setup, refer to Configuring Providers.

Zero-key paths (Piper TTS, stock media, Remotion/HyperFrames) remain usable even without API keys.