Skip to Content
NexTube 3.0 is released 🎉
InstallationTroubleshooting

Troubleshooting

Resolve common issues encountered during the NexTube installation process on VPS, PaaS, or localhost with this comprehensive troubleshooting guide.

If you’re experiencing difficulties during the NexTube installation or deployment process, this guide will help you identify and fix common issues. Below you’ll find error categories with detailed solutions.

Before You Begin

Before diving into specific problems, ensure the following:

  1. Your system meets all server requirements.
  2. You’re using the latest version of the NexTube ZIP archive.
  3. You’ve followed the appropriate installation guide for your environment:
    VPS, PaaS, or Localhost.

Common Issues and Solutions

  • 404 Error at /install or Blank Page

If you open /install and get a 404 error or a blank screen:

  1. Check Nginx or hosting config: Make sure your Nginx (or other proxy) is pointing to the install folder inside your project:
root /var/www/youtube-clone/install;

  • Database Connection Errors

If you get a “Database Error” or “Failed to connect to NeonDB” message:

  1. Incorrect URI in the .env:
    • Neon DB
DATABASE_URL=postgresql://USER:PASSWORD@HOST/DB_NAME?sslmode=require

  • Installation Wizard Fails or Doesn’t Load

If the /install page fails to load, shows a spinner forever, or crashes:

  1. Check server logs:

    pm2 logs
  2. Missing .env or config issues: During installation, no .env file is required — all variables are created automatically. Do not attempt to preconfigure .env.

  3. Browser cache: Clear the browser cache or try opening /install in incognito mode.

  4. SSL misconfig: If using HTTPS, verify your SSL certificate and redirect rules (especially with Nginx or Cloudflare).


  • Server Crashes or Restarts on Its Own

If the Node.js server crashes after install or mid-use:

  1. Check PM2 logs:

    pm2 logs youtube-clone
  2. Uncaught exceptions: Common causes include:

    • Invalid NeonDB connection
    • Out-of-memory issues on small VPS (upgrade to at least 2GB RAM)
  3. Fix file permission issues:

    chown -R www-data:www-data /var/www/youtube-clone
  4. Restart PM2 properly:

    pm2 restart youtube-clone

  • 500 Internal Server Error or App Not Responding
  1. Check PM2 logs:

    pm2 logs medium-clone
  2. Static files not found: NexTube ships with a prebuilt frontend. If you see static file errors, ensure the contents of the client/build or embedded React build are present inside the public folder. You should not need to rebuild anything.

  3. Insufficient resources: VPS must have at least 2GB RAM. Use htop or top to monitor memory usage.

  4. Port already in use: Make sure no other service (e.g., previous Node process) is running on the same port.

Additional Debugging Tips

  1. Always check PM2 logs:

    pm2 logs
  2. If using Nginx, check:

    sudo cat /var/log/nginx/error.log
  3. Inspect your NeonDB connection separately using a tool like NeonDB.

  4. Verify SSL and HTTPS redirect rules are correctly set up if you enabled HTTPS.

Getting Further Help

If you’re still facing issues:

  1. Collect the following information:

    • Error logs (pm2 logs, Nginx logs)
    • VPS specs (RAM, OS version)
    • Steps to reproduce the error
    • Screenshot or full error message
  2. Contact our support team:
    đź“© support@jooj.us

    Most issues are solved by checking the logs and carefully reviewing each step of the installation. If something fails, don’t panic — 90% of problems are minor misconfigurations or missing steps.