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.