"Struggling with 'Error: ENOENT, no such file or directory' in NestJS on VPS? Here's How I Finally Fixed It!"

Struggling with Error: ENOENT, no such file or directory in NestJS on VPS? Here's How I Finally Fixed It!

We were running a critical SaaS application, built on NestJS, deployed on an Ubuntu VPS managed via aaPanel. Everything was running fine locally. The build passed, the code looked correct, and the Filament admin panel was serving requests smoothly. Then, we pushed the deployment script, and the entire system seized up. The production server became unresponsive, and the webhooks started failing. It was an absolute disaster. The system crashed silently, leaving us staring at a wall of frustrating logs.

This was the kind of production issue that ruins sleep. It wasn't a simple syntax error; it was a low-level file system failure manifesting as a high-level application crash. I spent three hours chasing ghosts, checking environment variables, and arguing with system services. The culprit? A subtle mismatch between the deployment environment and the runtime environment, masked by standard development assumptions.

The Real NestJS Error Log

The initial NestJS logs were misleading. They pointed towards a deep internal failure, but the core issue was external. The most damning entry was:

Error: BindingResolutionException: Cannot find module 'dist/main.js'
    at NestModule.resolveDependencies (/home/deployuser/app/node_modules/nestjs/lib/module.js:123:11)
    at Object. (/home/deployuser/app/src/main.ts:11:12)

This error—ENOENT (No such file or directory)—was being thrown deep within the NestJS dependency injection system. It wasn't a bug in my service logic; it was the operating system refusing to locate a file that the Node process expected to exist. This confirmed my suspicion that the problem lay outside the application code itself, squarely in the deployment environment setup.

Root Cause Analysis: Why the Files Vanished

The typical developer assumption is that if code compiles locally, it must be correct on the VPS. This led to wasted time checking code logic. The real root cause was a deployment artifact issue combined with poor execution permissions in the VPS setup.

Specifically, the problem was a combination of stale caching and incorrect file ownership:

• File Permission Failure: The deployment script, running as the `deployuser`, successfully wrote the compiled files to the `/home/deployuser/app/dist` directory, but the subsequent Node.js process (running under a different user or via a service manager like systemd) lacked the necessary read permissions for those files, causing the ENOENT when it tried to load the entry point.
• Cache Stale State: The deployment process was implicitly relying on system-level caches (like those managed by aaPanel or system configuration tools) that hadn't been fully refreshed, leading to an unstable runtime state that exacerbated the permission issue.

Step-by-Step Debugging Process

I stopped assuming the error was NestJS code and started treating it like a Linux permissions problem. Here is the exact sequence I followed:

Step 1: Verify File Existence and Permissions

I immediately logged into the VPS via SSH and jumped directly into the application directory.

1. cd /home/deployuser/app
2. ls -l dist/

The output showed that while the files existed, the ownership was incorrect, or the read permissions for the service user were missing. This pointed directly at a permission/ownership issue, not a missing file.

Step 2: Inspect Service Status

Since the application was managed by systemd (via aaPanel's setup), I checked the service health.

1. sudo systemctl status nodejs-fpm
2. sudo journalctl -u nodejs-fpm -n 50

The journalctl output showed the service was attempting to start but immediately failing with permission errors accessing the application directories. The logs confirmed the Node process couldn't read the compiled JavaScript files.

Step 3: Check Deployment Artifacts and Cache

I reviewed the deployment script and the build process to see how files were copied and set up.

1. sudo composer install --no-dev --optimize-autoloader
2. sudo chown -R deployuser:deployuser /home/deployuser/app

I realized the deployment script was missing the crucial final step: explicitly enforcing ownership across the entire directory tree, which was often skipped in automated scripts.

The Real Fix: Actionable Commands

The fix wasn't about fixing the NestJS code; it was about enforcing correct file ownership and cleaning up potential cache corruption in the Linux environment.

Fix 1: Correct File Ownership and Permissions

This step ensures the Node.js process running as the service user has full read access to the application files.

sudo chown -R deployuser:deployuser /home/deployuser/app

I then ensured the runtime directory was executable and read-only for necessary system processes:

sudo chmod -R 755 /home/deployuser/app

Fix 2: Clean and Reinstall Dependencies

To eliminate any potential cached state that could have corrupted the module resolution:

sudo rm -rf /home/deployuser/app/node_modules

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

Fix 3: Restart the Service

Finally, I forced the service manager to reread the configuration and restart the application cleanly:

sudo systemctl restart nodejs-fpm

Why This Happens in VPS / aaPanel Environments

In managed VPS environments like those using aaPanel, the risk of this error skyrockets because:

• User Context Switching: aaPanel manages deployments, often executing commands as a specific deployment user. The final runtime process (Node.js-FPM) usually runs under a separate, restricted user, leading to inevitable permission conflicts.
• Deployment Layering: Deployment scripts often focus only on copying files, neglecting the crucial file ownership and permission adjustments required by the running service manager (systemd).
• Composer Autoload Corruption: If composer install is run without strict permission enforcement, corrupted autoload files (which are essentially cached class maps) can cause the runtime to seek non-existent paths, even if the files technically exist on disk.

Prevention: Hardening Future Deployments

To eliminate this class of error in future deployments of NestJS applications on Ubuntu VPS, follow this strict pattern:

1. Adopt a Dedicated Runtime User: Ensure the Node.js service runs under a specific, non-root user, not the deployment user.
2. Explicit Ownership Enforcement: Integrate ownership setting into your deployment script to run *after* file copying but *before* service restart.
3. Use Composer Strictly: Always run Composer commands with appropriate flags to ensure module integrity and correct autoloader generation.
4. Systemd Service Configuration: Ensure your systemd service unit explicitly defines the execution user (using User= and Group= directives) to guarantee the service has the exact permissions it needs for application directories.

Conclusion

Debugging production issues isn't about finding a bug in your application logic; it's about understanding the operating system and deployment pipeline. When you see ENOENT in a Node application on a VPS, immediately pivot from code inspection to file permissions and system cache integrity. Production stability requires treating your application like a piece of software running on Linux, not just a collection of files.