"NestJS on Shared Hosting: Frustrated with 'ENOENT' Errors? Fix Now!"

NestJS Deployment on Shared Hosting: Frustrated with ENOENT Errors? Fix Now!

We deployed a new NestJS microservice on an Ubuntu VPS managed via aaPanel, integrating it with Filament for the admin panel. The initial deployment seemed smooth, but about an hour after the traffic started flowing, the entire application went silent. Our users were hitting 500 errors, and the Filament dashboard was completely inaccessible. The panic started when the critical queue worker failed, and the system, designed for high throughput, simply choked.

This wasn't a local bug; this was a production nightmare on a shared, containerized VPS environment. I spent three hours chasing phantom errors, realizing the issue wasn't in the TypeScript code itself, but in the subtle, painful interaction between the Node.js process manager, the web server configuration, and the file system permissions imposed by the hosting environment.

The Actual NestJS Error Message

The initial pain manifested in the NestJS log files. When attempting to restart the service, the application throws a classic file system error, masquerading as a runtime crash:

[ERROR] NestJS Runtime Error: ENOENT: no such file or directory, open '/var/www/myapp/node_modules/express/lib/router/index.js'
Stack Trace:
    at Object. (/var/www/myapp/src/main.ts:15:12)
    at Module._compile (node:internal/modules/cjs/loader:1104:12)
    at Module._extensions..js (node:internal/modules/cjs/loader:1124:10)
    at Object.load (node:internal/modules/fs:1051:32)
    at require (node:internal/modules/cjs/mjs:110:18)
    at require (./node_modules/express/lib/router/index.js:1:1)
    at Module._load (node:internal/modules/modules:45:10)
    at processTicksAndRejections (node:internal/process/task_queues:95:5)

Root Cause Analysis: The Hidden Deployment Drift

The error ENOENT: no such file or directory is classic, but it was misleading. The application wasn't missing a file; it was missing a dependency that the Node.js runtime was trying to load. The specific issue here was a cache and permission mismatch combined with how the deployment script handled dependency installation on the VPS.

The core problem was a cache and permissions issue combined with the file structure created by aaPanel's deployment process. When we ran npm install, some dependencies were installed into a location that the subsequent Node.js process (running under the specific user context defined by aaPanel) could not correctly access or resolve, specifically affecting the node_modules path. Furthermore, running processes like Node.js-FPM and supervisor were fighting over stale configuration state, leading to the service failing immediately upon startup.

Step-by-Step Debugging Process

We needed to treat this like a forensic investigation, ignoring the superficial error message and focusing on the environment state.

Step 1: Validate Process Status

First, check the health of the running application and associated worker processes:

• sudo systemctl status nodejs-fpm
• sudo systemctl status supervisor
• sudo htop (To check actual CPU/Memory load and identify hung processes)

Step 2: Inspect Application Logs

The most reliable source is the system journal, which captures the daemon failures:

sudo journalctl -u nodejs-fpm -n 50 --no-pager

The logs confirmed repeated failed attempts to load modules, pointing directly to the file system access failure.

Step 3: Verify File Permissions and Ownership

This was the critical step. We checked the ownership of the application directory and the dependencies:

ls -ld /var/www/myapp/

ls -l /var/www/myapp/node_modules/

The ownership was often incorrect, and crucial files were owned by the deployment user, not the Node.js execution context.

Step 4: Deep Dive into Composer and Module Integrity

We ran a manual dependency check and forced a fresh installation, ensuring the node_modules directory was pristine:

cd /var/www/myapp

rm -rf node_modules

composer install --no-dev --optimize-autoloader

The Real Fix: Enforcing Environment Integrity

The fix wasn't just reinstalling dependencies; it was enforcing the correct ownership and ensuring the deployment process respected the file system state. We implemented a script pattern to run the dependency installation with proper ownership:

Fix 1: Correct Ownership and Permissions

Ensure all application files and dependencies are owned by the user context running the Node.js service (often `www` or the specific deployment user defined in aaPanel):

sudo chown -R www:www /var/www/myapp/

sudo chmod -R 755 /var/www/myapp/

Fix 2: Production-Ready Dependency Rebuild

We modified the deployment sequence to explicitly clean and rebuild the dependencies *before* starting the service:

cd /var/www/myapp

rm -rf node_modules package-lock.json

npm install --production

Fix 3: Supervisor Configuration Correction

We checked the supervisor configuration to ensure the node.js-fpm process was started with correct working directories and environment variables, preventing stale state issues:

sudo nano /etc/supervisor/conf.d/myapp.conf

(Ensuring the command executed was correctly pointing to the main application entry point and respecting the current working directory.)

Why This Happens in VPS / aaPanel Environments

The complexity of deploying NestJS on aaPanel-managed Ubuntu VPS introduces specific friction points:

• User Context Mismatch: Deployment scripts often run as `root`, but the Node.js process runs under a restricted user (e.g., `www`). This creates immediate permission conflicts when accessing dynamically generated files in node_modules.
• Cache Stale State: Shared hosting environments rely heavily on caching (Opcode cache, system caches). If a dependency installation or file change occurs, but the system cache is not flushed or rebuilt, the running application loads stale, broken paths, leading to ENOENT errors upon execution.
• Process Manager Overhead: Using process managers like supervisor requires careful setup. If the supervisor script doesn't correctly handle environment inheritance or working directories, the spawned Node.js processes fail immediately upon invocation.

Prevention: Hardening Future Deployments

To prevent recurring NestJS error failures during future deployments, follow this strict pattern for all Node.js-based applications on VPS:

1. Use Dedicated Deploy User: Ensure your deployment pipeline runs commands using the exact user that the application service will run as (e.g., www).
2. Isolate Node/NPM Execution: Run npm install and composer install *after* ensuring correct permissions are set for the application directory, rather than letting the deployment script run these commands as root.
3. Atomic Dependency Management: Always commit and manage package-lock.json or composer.lock files alongside your code. Never manually delete node_modules in production unless performing a full rebuild.
4. Supervisor Health Checks: Configure supervisor to monitor for specific exit codes and ensure a graceful restart sequence is implemented, checking application logs immediately upon failure.

Conclusion

Production deployment is not just about writing clean TypeScript; it's about mastering the operating system layer. Stop assuming the error is in your code. When you see ENOENT in a shared environment, immediately step away from the application logic and start debugging the permissions, caches, and process management of your Ubuntu VPS. Real production debugging lives in the difference between what the code says and what the machine actually does.