A beginner-friendly guide to understanding Node.js and troubleshooting it on Hostinger
Business & Cloud Hosting Planspackage.json. Then, we install it for client! No npm command needed.
npm stands for Node Package Manager. Think of it as an app store for Node.js code. Developers use it to install ready-made tools (called "packages" or "dependencies") so they don't have to build everything from scratch.
Example: Instead of writing your own code to connect to a database, you install a package that already does it.
Developers often use frameworks (pre-built structures) on top of Node.js. Hostinger supports:
| Framework | What It's Good For |
|---|---|
| Next.js | Full websites with both frontend and backend (very popular!) |
| React | Interactive user interfaces |
| Vue.js | Flexible, easy-to-learn frontend framework |
| Angular | Large-scale single-page applications |
| Vite | Super-fast build tool for modern web apps |
| Express.js | Lightweight backend/API server |
When someone visits your Node.js website, here's what happens behind the scenes:
When you upload your Node.js project to Hostinger, the platform does this automatically:
package.json — the file that lists your app's settings and dependenciesnpm run build)When Hostinger deploys your Node.js app, it doesn't know what tools and libraries your app needs to run. The package.json file is that shopping list — it tells Hostinger exactly what to install.
When you click Deploy or Redeploy in hPanel, Hostinger reads this file and automatically installs Node.js and every package listed under "dependencies". You don't need to do anything manually — it all happens behind the scenes.
Here's what a typical package.json looks like and what each part means:
// package.json — your app's ID card & shopping list { "name": "my-website", // the name of your project "version": "1.0.0", // the version of your project "engines": { "node": "20.x" // which Node.js version to use }, "scripts": { "build": "next build", // command to build the app "start": "next start" // command to start the app }, "dependencies": { "next": "14.0.0" // ✅ installed on server — needed to RUN the app }, "devDependencies": { "eslint": "8.0.0" // ❌ NOT installed on server — only for development } }
devDependencies by mistake, Hostinger won't install it — and your app will crash.
"dependencies", NOT "devDependencies". This is one of the most common causes of deployment failures.These are secret settings your app needs — like database passwords or API keys. They're stored separately from your code so they're not exposed publicly.
DB_HOST=localhost DB_PASSWORD=mypassword PORT=3000 NODE_ENV=production
On Hostinger, you set these in hPanel → Website Dashboard → Environment Variables.
Just like apps have versions, so does Node.js. Hostinger supports:
Your project's package.json should specify which version it needs. Mismatches cause build failures.
GitHub Integration — Connect your GitHub repo. Every time you push code, Hostinger automatically rebuilds and redeploys. Best for active projects.
ZIP Upload — Upload a compressed file of your project. Simpler, good for static projects. Don't include the node_modules folder in the ZIP!
When something goes wrong, logs tell you exactly what happened. There are two types — and knowing which one to check first saves a lot of time:
Path: hPanel → Websites → Dashboard → Deployments
Node.js apps often need a database to store data. On Hostinger, you can connect to our database or Supabase
DB_HOST=localhost
DB_PORT=3306
DB_USER=databaseuser
DB_PASSWORD=databasepassword
DB_NAME=databasename
DATABASE_URL=mysql://databaseuser:databasepassword@localhost:3306/databasename
Node.js applications are available on: Business Hosting Cloud Hosting
📖 Full guide: How to add a Node.js Web App in Hostinger
Before diving into specific errors, always follow this two-step approach:
Simple rule: deployment failure = Build Log. Post-deployment issue = Runtime Log / stderr.log.
BUILD ERROR This is the most common error. It means the deployment engine couldn't complete the build process. Always check the Build Log first.
| Cause | How to Fix |
|---|---|
| Wrong Node.js version selected | Go to Deployments → Settings and redeploy → match the version in your package.json engines field. Supported: 18.x, 20.x, 22.x, 24.x |
package.json not found |
For GitHub: make sure package.json is committed. For ZIP: ensure it's at the root of the archive, not inside a subfolder |
| Wrong framework selected | In Deployments → Settings, confirm the framework matches your actual project (e.g., Next.js, React, Vue) |
| Wrong root directory | Verify the root directory setting matches where your package.json actually lives |
| Runtime packages in devDependencies | Move packages your live app needs from devDependencies to dependencies in package.json |
| node_modules included in ZIP | Remove the node_modules folder before zipping. Hostinger installs them automatically from package.json |
These errors appear after deployment. The app is running but something is wrong. Check Runtime Logs or stderr.log to find the cause.
The app is deployed but not responding. Most common right after deployment.
TEST=test) and redeploy. This often resolves the 503.The app crashed or is returning errors. Check Runtime Logs or stderr.log first.
domain.tld/hbuilds/current/nodejs/stderr.logUsually caused by missing or incorrect .htaccess configuration after deployment.
public_html.htaccess exists inside public_html.htaccess routing rules are correct for your framework.htaccess rules accordinglyIf env variables aren't being applied even after setting them in hPanel, use this manual workaround:
domain.tld/hbuilds/current/nodejs/).envAPI_KEY=12345Add this to the very top of your .htaccess file:
<Files .env> Order allow,deny Deny from all </Files>
Via SSH: touch tmp/restart.txt
Or via hPanel: Website Dashboard → Restart button
These record everything that happens during the deployment process. If the app never started, start here.
📍 hPanel → Websites → Dashboard → Deployments → [failed build] → Build Logs
These record what happens while the app is running. Crashes, unhandled errors, and missing modules show up here.
📍 hPanel → Websites → [Your Node.js site] → Dashboard → Runtime Logs
Note: If deployed before Runtime Logs was released, redeploy first. Static sites (Vite, React static) won't produce runtime logs — only server-side apps do (Next.js, Express).
This file captures crash output. If the app starts then immediately dies, this is where to look.
📍 hPanel → File Manager → domain.tld/hbuilds/current/nodejs/stderr.log
If empty: ask customer to redeploy and re-check, or check stdout.log instead.
| Error Message | Cause | Fix |
|---|---|---|
| "Access denied for user" | Wrong DB username or password | Verify credentials in hPanel and ensure the MySQL user is linked to the database |
| "Cannot connect to MySQL server" | Wrong host or port | Set host to localhost and port to 3306 |
| "DATABASE_URL is not defined" | Missing environment variable | Add the variable in hPanel → Environment Variables, then restart the app |
| App crashes after DB config change | New env vars not loaded | Restart app: hPanel → Restart, or SSH: touch tmp/restart.txt |
If you need to reinstall dependencies or run npm scripts, the solution is to Redeploy your application — this triggers the platform to read your package.json, reinstall all packages, and rebuild automatically.
Before escalating or contacting support, go through this checklist:
engines field in package.jsonpackage.json exists at the project root (not inside a subfolder)dependencies, not devDependenciesnode_modules folderproduction.htaccess exists inside public_html.htaccess has correct routing rules for the frameworkNODE_ENV=productionnode_modules in ZIP