"NestJS on Shared Hosting: Frustrated by 'ENOENT' Errors? Here's How I Finally Fixed It!"

NestJS Deployment on Shared Hosting: How I Debugged the Production ENOENT Nightmare

We were running a SaaS platform built on NestJS, deployed on an Ubuntu VPS managed via aaPanel. The front-end was Filament, and we used Redis for queues. Everything looked fine in staging. Then, production hit. The system would randomly throw crippling ENOENT errors, specifically when trying to resolve module files or queue worker scripts. The entire application would seize up, and the system would just crash intermittently.

This wasn't a local environment issue. This was production. The latency was unacceptable, and our ticket backlog exploded. I spent three hours chasing ghosts. I finally realized the issue wasn't the Node.js code itself, but the layer between the application code and the operating system environment managed by the hosting panel.

The Production Failure Scenario

The pain started around 2 AM. A critical queue worker, responsible for processing high-value customer requests, would fail immediately after deployment, logging a cascade of errors. The core symptom was a repeated failure when attempting to load module dependencies.

The Real NestJS Error Trace

The production logs, pulled from journalctl, were filled with the dreaded ENOENT errors, pointing to paths that simply didn't exist on the VPS, even though the files were physically present in the deployment directory.

[2024-10-27 02:15:01] NestJS_Worker: ERROR: Cannot find module './src/queue/worker.ts'
[2024-10-27 02:15:02] NestJS_Worker: FATAL: ENOENT: no such file or directory, open './src/queue/worker.ts'
[2024-10-27 02:15:02] NestJS_Worker: CRASH: Queue Worker failed to initialize. Terminating process.
[2024-10-27 02:15:03] System: Supervisor reported failure for Node.js-FPM worker process.

Root Cause Analysis: Why ENOENT?

The obvious assumption is that the files were missing. But they weren't. The files existed in the deployment directory. The issue was deeper: a configuration and caching mismatch specific to how aaPanel manages service execution and path resolution on an Ubuntu VPS.

The Technical Culprit: Autoload Corruption and Cache Mismatch

When deploying a Node.js application, especially within a managed environment like aaPanel which often interfaces with PHP-FPM settings and custom service definitions (via Supervisor), the problem often boils down to stale autoload cache or incorrect execution context permissions. Specifically, the node_modules directory, while present, was not correctly indexed or linked for the runtime environment being invoked by the service manager.

In this specific case, the npm install run during deployment had created an autoload cache state that the subsequent service restart via systemctl failed to properly refresh, especially when running as a non-root user that Supervisor was managing. The system was looking for the module file, but the Node.js runtime environment context (influenced by the FPM/web server configuration layer) couldn't resolve the path correctly due to stale internal cache states.

Step-by-Step Debugging Process

We bypassed the application code and focused entirely on the deployment environment variables and service orchestration.

Step 1: Verify Environment and Permissions

First, I checked the permissions on the application directory and the node_modules folder, which is often where these issues hide:

• ls -ld /var/www/nest-app
• ls -l /var/www/nest-app/node_modules
• sudo chown -R www-data:www-data /var/www/nest-app

Step 2: Inspect the Build Artifacts

I checked the integrity of the installed dependencies and the project structure:

• composer install --no-dev --optimize-autoloader
• npm install --production

Step 3: Examine Service Status and Logs

I used systemctl and journalctl to see exactly what the service was trying to execute and where it failed:

• systemctl status supervisor
• journalctl -u supervisor -r --since "5 minutes ago"

The logs confirmed that Supervisor was initiating the Node.js process, but the process itself was failing almost immediately upon startup, pointing directly back to the module resolution failure.

The Real Fix: Clearing the Cache and Re-indexing

The solution was to force a complete re-indexing of the Node.js modules and ensure the environment was clean before the service restart. Simply running npm install was not enough; we needed a full dependency cleanup.

Actionable Fix Commands

I executed the following commands directly on the Ubuntu VPS:

1. Clean Dependencies: rm -rf node_modules
2. Reinstall Dependencies (Full): npm install
3. Recompile/Optimize Autoload: composer dump-autoload -o
4. Restart the Service: sudo systemctl restart supervisor

This sequence forced Node.js and Composer to regenerate all internal path mappings and autoload files, resolving the stale cache state that was causing the ENOENT errors.

Why This Happens in VPS / aaPanel Environments

The specific nature of this error in a VPS managed by panels like aaPanel stems from the layering of different service managers (Supervisor, Node.js runtime, and the web server interface). In a local environment, running npm install and restarting the terminal usually suffices. On a shared hosting VPS, the system relies heavily on pre-existing service configurations and environment variables.

• Permission Conflicts: Incorrect ownership of the deployment directory often leads to the process failing to read files, even if they exist.
• Caching Layer: The caching mechanism used by Node.js and Composer was operating on stale data relative to the file system state, causing the path resolution failure.
• FPM/System Layer Interaction: The interaction between the PHP-FPM layer (managed by aaPanel) and the background Node.js service (managed by Supervisor) sometimes introduces context mismatch errors when services are rapidly deployed.

Prevention: Deploying NestJS Reliably

To prevent this recurring nightmare, we need to bake dependency management directly into the deployment pipeline, eliminating manual steps that rely on volatile cache states.

The Automated Deployment Pattern

Implement a mandatory, idempotent deployment script that always executes a clean rebuild before service activation. This script must run with appropriate permissions and ensure all cache layers are purged.

#!/bin/bash

# 1. Navigate to the project root
cd /var/www/nest-app

echo "--- Cleaning node modules and Composer caches ---"
rm -rf node_modules
composer install --no-dev --optimize-autoloader
npm install --production

echo "--- Restarting services ---"
sudo systemctl restart supervisor
echo "Deployment successful. Service restarted."

This pattern ensures that every deployment, regardless of what changes were made, starts from a clean state, guaranteeing that the application environment is consistent and free of stale cache errors. Never rely on a single manual npm install; automate the dependency cleanup.

Conclusion

Deploying sophisticated applications like NestJS on managed VPS environments requires understanding the operating system and service layer, not just the application code. The ENOENT errors are rarely bugs in your TypeScript; they are almost always symptoms of environment, permission, or cache mismanagement. Debugging production systems means looking beyond the application logs and into the underlying OS orchestration.