Troubleshooting

This guide covers common issues you might encounter and how to resolve them.

Setup Issues

Permission denied errors during npm install Run with sudo if needed: sudo npm install. On Windows, run terminal as administrator.

Python command not found Ensure Python 3.8+ is installed and available as python or python3. Install from python.org or use your system package manager.

Git clone fails with permission errors Use HTTPS instead of SSH: git clone https://github.com/lissy93/framework-benchmarks.git

Setup hangs or times out This usually happens during npm install for frameworks. Wait for completion (can take 10+ minutes) or check your network connection.

Build Issues

Individual framework build fails Check the specific framework's logs. Common causes: - Missing dependencies (run npm install in the framework directory) - Node.js version compatibility (ensure Node.js 18+) - Disk space issues (each build needs ~100MB)

Angular build fails with memory errors Increase Node.js memory: NODE_OPTIONS="--max-old-space-size=4096" npm run build:angular

Build output directory not found Different frameworks use different output directories. Check apps/{framework}/dist/ or apps/{framework}/build/.

Server Issues

Port 3000 already in use Kill the existing process: pkill -f ":3000" or use a different port with npm start -- --port 3001

Framework shows 404 or not found Ensure the framework is built first with npm run build:{framework} before starting the server.

Server starts but frameworks don't load Check that build outputs exist in the correct directories. Run ls apps/{framework}/dist/ to verify.

Benchmark Issues

Chrome not found for Lighthouse Install Chrome or Chromium: - Ubuntu/Debian: sudo apt install chromium-browser - macOS: Install Chrome from google.com/chrome - Windows: Install Chrome from google.com/chrome

Benchmark results are inconsistent Use multiple executions for more reliable results: python scripts/benchmark/main.py all --executions 3

Bundle size analysis shows zero The frameworks need to be built first: npm run build before running bundle analysis.

Lighthouse fails with connection errors Ensure the server is running (npm start) and accessible at http://localhost:3000 before running benchmarks.

Docker Issues

Docker build fails Ensure you have sufficient disk space (build needs ~2GB) and Docker is running.

Container starts but benchmarks fail Use the correct Chrome flags for containers: CHROME_FLAGS='--no-sandbox --disable-dev-shm-usage --headless'

General Tips

Check logs - Most scripts provide detailed error messages. Read them carefully for specific guidance.

Clean and retry - Try npm run clean followed by a fresh setup if builds are behaving unexpectedly.

Check dependencies - Ensure all system requirements (Node.js 18+, Python 3.8+, Chrome) are installed and up to date.

Disk space - The full project with all frameworks built needs ~5GB of disk space.