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:
- Your system meets all server requirements.
- You’re using the latest version of the NexTube ZIP archive.
- 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:
- 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:
- 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:
-
Check server logs:
pm2 logs
-
Missing .env or config issues: During installation, no
.env
file is required — all variables are created automatically. Do not attempt to preconfigure.env
. -
Browser cache: Clear the browser cache or try opening
/install
in incognito mode. -
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:
-
Check PM2 logs:
pm2 logs youtube-clone
-
Uncaught exceptions: Common causes include:
- Invalid NeonDB connection
- Out-of-memory issues on small VPS (upgrade to at least 2GB RAM)
-
Fix file permission issues:
chown -R www-data:www-data /var/www/youtube-clone
-
Restart PM2 properly:
pm2 restart youtube-clone
- 500 Internal Server Error or App Not Responding
-
Check PM2 logs:
pm2 logs medium-clone
-
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 thepublic
folder. You should not need to rebuild anything. -
Insufficient resources: VPS must have at least 2GB RAM. Use
htop
ortop
to monitor memory usage. -
Port already in use: Make sure no other service (e.g., previous Node process) is running on the same port.
Additional Debugging Tips
-
Always check PM2 logs:
pm2 logs
-
If using Nginx, check:
sudo cat /var/log/nginx/error.log
-
Inspect your NeonDB connection separately using a tool like NeonDB.
-
Verify SSL and HTTPS redirect rules are correctly set up if you enabled HTTPS.
Getting Further Help
If you’re still facing issues:
-
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
- Error logs (
-
Contact our support team:
📩 support@jooj.usMost 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.