Troubleshooting Guide

Solutions for common issues.

Table of contents

1. Installation Issues
   1. “Python not configured”
   2. “Module not found” errors
   3. “MPS not available”
2. Generation Issues
   1. “Generation Failed” error
   2. Black video output
   3. Very slow generation
3. Memory Issues
   1. “Out of memory” or crash
   2. Model download stuck
4. App Issues
   1. App won’t launch
   2. Preferences not saving
   3. Videos not appearing in History
5. Getting More Help
   1. Debug Logging
   2. Python Environment Test
   3. Report an Issue

---

Installation Issues

“Python not configured”

Problem: App shows Python not configured error.

Solution:

1. Open Preferences (⌘,)
2. Enter the full path to your Python executable
3. Click Validate
4. Ensure you see version information

Finding your Python path:

# Virtual environment
~/ltx-venv/bin/python3

# pyenv
~/.pyenv/versions/3.11.9/bin/python3

# Check with which
which python3

“Module not found” errors

Problem: Missing Python packages.

Solution:

# Activate your environment first
source ~/ltx-venv/bin/activate

# Install missing packages
pip install torch diffusers accelerate transformers
pip install safetensors sentencepiece
pip install imageio imageio-ffmpeg opencv-python

“MPS not available”

Problem: Metal Performance Shaders not detected.

Causes:

• Not running on Apple Silicon
• Outdated PyTorch version
• Environment issue

Solution:

# Check MPS availability
python3 -c "import torch; print(torch.backends.mps.is_available())"

# If False, update PyTorch
pip install --upgrade torch torchvision torchaudio

---

Generation Issues

“Generation Failed” error

Problem: Generation starts but fails partway through.

Check the logs:

1. Look at /tmp/ltx_generation.log
2. Or run the Python script manually to see errors

Common causes:

• Out of memory (reduce resolution/frames)
• Model not fully downloaded
• Network issue during model download

Solution:

# Clear partially downloaded model
rm -rf ~/.cache/huggingface/hub/models--a-r-r-o-w--LTX-Video*

# Retry - model will redownload

Black video output

Problem: Video generates but appears completely black.

Cause: Usually a precision/dtype issue with MPS.

Solution: The app uses bfloat16 which is compatible with MPS. If you’re building from source, ensure:

torch_dtype=torch.bfloat16  # NOT float16

Very slow generation

Problem: Generation takes much longer than expected.

Solutions:

1. Check that MPS is being used (not CPU)
2. Close other memory-intensive applications
3. Reduce resolution or frame count
4. Ensure you’re using a supported preset

---

Memory Issues

“Out of memory” or crash

Problem: App crashes during generation.

Solutions:

1. Reduce resolution:
   • Use 512×320 instead of higher resolutions
2. Reduce frame count:
   • Start with 25 frames
3. Close other apps:
   • Safari, Chrome use significant memory
   • Other ML applications
4. Check available memory:

   # In Terminal
   vm_stat | head -5
   

Model download stuck

Problem: Model download appears stuck or very slow.

Solutions:

1. Check internet connection
2. Try again later (HuggingFace servers may be busy)
3. Download manually:

   huggingface-cli download a-r-r-o-w/LTX-Video-0.9.1-diffusers
   

---

App Issues

App won’t launch

Problem: App bounces in dock but won’t open.

Solutions:

1. Right-click and select “Open” for first launch
2. Check System Settings > Privacy & Security
3. Try moving to Applications folder
4. Verify notarization:

   spctl -a -vv "/Applications/LTX Video Generator.app"
   

Preferences not saving

Problem: Settings reset after restart.

Solution:

1. Check write permissions to preferences:

   ls -la ~/Library/Preferences/com.jamescampbell.ltxvideogenerator.plist
   

2. Reset preferences:

   defaults delete com.jamescampbell.ltxvideogenerator
   

Videos not appearing in History

Problem: Generated videos don’t show in History tab.

Check:

1. Look in the default output folder (~/Movies/LTXVideoGenerator/)
2. Verify the video file exists
3. Check that thumbnails are being generated

---

Getting More Help

Debug Logging

Check the generation log:

cat /tmp/ltx_generation.log

Python Environment Test

# Test your Python setup
python3 << 'EOF'
import torch
print(f"PyTorch: {torch.__version__}")
print(f"MPS available: {torch.backends.mps.is_available()}")

from diffusers import LTXPipeline
print("Diffusers: OK")

import imageio
print("imageio: OK")

print("\nAll checks passed!")
EOF

Report an Issue

If problems persist:

1. Check existing GitHub Issues
2. Open a new issue with:
   • macOS version
   • Mac model (M1/M2/M3)
   • Python version
   • Error message or log output
   • Steps to reproduce