Troubleshooting

Installation

Node Issues

# clear cache
npm cache clean --force

# reinstall
rm -rf node_modules package-lock.json
npm install

Remove-Item -Recurse -Force node_modules, package-lock.json
npm install

Development Server

Port 3000 in use

# use different port
npm run dev -- --port 3001

Supabase connection errors

• Check app/.env (or app/.env.local) exists
• Verify NUXT_PUBLIC_SUPABASE_URL is correct
• Verify NUXT_PUBLIC_SUPABASE_ANON_KEY is correct
• Check Supabase project is active

TMDB API errors

• Verify NUXT_TMDB_API_KEY is set
• Confirm the TMDB API key is valid and active
• Check server logs for upstream TMDB errors

Build Issues

Cannot find module errors

# rebuild
rm -rf .nuxt
npm run build

Remove-Item -Recurse -Force .nuxt
npm run build

Slow build

• Close other apps
• Check disk space
• Run on SSD for faster I/O

"'nuxt' is not recognized" in docs/

cd docs
npm install

API Issues

API Endpoints Returning 404

Problem: API calls fail with 404 errors.

Solution:

• Verify the app server is running (cd app && npm run dev)
• Check API base URL in configuration
• Ensure correct endpoint paths, especially /api/recommend, /api/movies/search, /api/movies/:id, /api/watched, and /api/mylist

Movies Not Appearing in Search

Problem: Movie data seems empty.

Solution:

• Verify TMDB requests are succeeding
• Check browser network tab for /api/movies/search?q=... responses
• Restart the app server

Common Error Messages

"ERR_MODULE_NOT_FOUND"

Solution:

• Check node_modules exists: npm install
• Verify tsconfig.json paths are correct
• Clear build cache: rm -rf .nuxt

"EACCES: permission denied"

Solution:

• Fix npm permissions using the official npm docs
• Use a Node version manager for better local setup

Database Issues

Supabase Connection Timeout

Problem: Auth requests timeout.

Solution:

• Check network connection
• Verify Supabase project status
• Confirm auth credentials in app/.env (or app/.env.local)

Getting Help

If issues persist:

1. Check documentation thoroughly
2. Review error logs in browser console (F12)
3. Check server logs in terminal
4. Submit a detailed issue report with the error message, reproduction steps, Node version, and OS information