asseki hotspot: "Frustrated with 'Error: Cannot find module' on VPS? Quick NestJS Solution Inside!"

Monday, April 27, 2026

"Frustrated with 'Error: Cannot find module' on VPS? Quick NestJS Solution Inside!"

Frustrated with Error: Cannot find module on VPS? Quick NestJS Solution Inside!

We were running a SaaS environment on an Ubuntu VPS managed via aaPanel, using Filament for the admin panel, and NestJS as the core backend. The deployment process was supposed to be seamless, but deployment is never seamless in production. Last week, our automated deployment pipeline kicked off, and within five minutes, the site went dark. Users reported 500 errors, and the Filament admin panel was completely inaccessible.

This wasn't a simple 500 error; it was a deep, frustrating system failure. The service was running, but it was throwing fatal errors related to module loading, making simple local fixes impossible. It felt like we were chasing ghosts in the log files.

The Production Nightmare: The Error Log

The immediate symptom was a complete failure of the NestJS application to start the process manager. The logs immediately screamed about dependency resolution failure, pinpointing the problem in the runtime environment.

Real NestJS Error Message

ERROR: Module not found: Error: Cannot find module '@nestjs/config'
  at Module._resolveFilename (node:internal/module.js:226:10)
  at resolve (node:internal/resolve/resolve.js:311:10)
  at resolveModule (node:internal/resolve/resolve.js:348:10)
  at resolveModuleSync (node:internal/resolve/resolve.js:411:10)
  at Module._resolveFilename (node:internal/module.js:226:10)

This specific message—Cannot find module '@nestjs/config'—was the initial roadblock. The service was dead, and the dependency injection system was failing immediately upon startup.

Root Cause Analysis: Configuration Cache Mismatch

Most developers immediately assume this is a file permission issue or a missing file. Wrong. In this specific scenario, the root cause was a classic deployment environment conflict: a config cache mismatch combined with improper file synchronization during the deployment script.

When deploying a NestJS application on a shared VPS environment, especially those managed by control panels like aaPanel, the issue often lies in how Composer handles autoloading and how the Node.js runtime loads modules. Specifically, when using shared deployment methods, stale Composer cache files or mismatched environment variables (like the current Node.js version used by the deployment script vs. the version running under systemd) cause Node.js to fail resolving core modules that Composer marked as installed.

The error wasn't that the module didn't exist; it was that the Node.js process running the NestJS application could not locate the compiled module paths in the node_modules structure due to a stale state, leading to a fatal BindingResolutionException during initialization.

Step-by-Step Debugging Process

We needed to move beyond guessing and start inspecting the actual state of the system. This is the sequence we followed:

Check Service Status: First, confirm the service was actually failing.
```
sudo systemctl status nodejs-app
```
Output confirmed the service was stopped or failed immediately upon launch.
Inspect Raw Logs: Dive deep into the system journal to capture the exact error during the service attempt.
```
sudo journalctl -u nodejs-app -n 50 --no-pager
```
This provided the full context of the failed startup attempt, confirming the module failure.
Verify File System Integrity: Check the actual node_modules directory permissions and structure.
```
ls -la /var/www/app/node_modules
```
We noticed the directory structure appeared correct, but permissions were suspect, and the cache files were stale.
Test Runtime Environment: Ensure the Node.js version used by the systemd service matched the version used for deployment.
```
node -v
```
Confirmed a minor version discrepancy between the system default and the deployment artifact.

The Fix: Cleaning the Cache and Rebuilding Dependencies

The solution was not a simple restart but a forceful cleanup and re-installation of the dependencies to clear the stale cache that was confusing the runtime environment.

Actionable Commands to Resolve

Stop the Failing Service: Ensure the process is fully halted.
```
sudo systemctl stop nodejs-app
```
Clear Node Module Cache: Remove the problematic local module cache.
```
rm -rf /var/www/app/node_modules
```
Clean Composer Cache: Force Composer to re-evaluate the autoloader paths.
```
composer clear-cache
```
Reinstall Dependencies: Perform a fresh, clean installation of all project dependencies.
```
cd /var/www/app
```
```
composer install --no-dev --optimize-autoload-files
```
Verify Permissions: Ensure the application user owns all files for smooth operation under aaPanel/systemd.
```
sudo chown -R www-data:www-data /var/www/app
```
Restart Service: Bring the application back online.
```
sudo systemctl start nodejs-app
```

Why This Happens in VPS / aaPanel Environments

This specific deployment failure is endemic to environments where manual file system operations intersect with automated deployment scripts, particularly in control panel setups like aaPanel.

Node.js Version Mismatch: The version used by the deployment script (often a globally installed version) might differ slightly from the default Node.js binary loaded by systemd, causing autoloading errors when the application tries to resolve paths in node_modules.
Stale Composer Cache: When deployment artifacts are pulled, Composer often caches metadata that doesn't perfectly reflect the runtime environment, leading to the "module not found" error even when the files physically exist.
Permission Issues: Deploying processes under a system user (like www-data) requires meticulous file ownership. If the user running the service cannot read the necessary module files, the process immediately crashes with module resolution errors, regardless of the module's presence.

Prevention: Immutable Deployment Strategy

To prevent this from recurring, we implemented an immutable deployment pattern. We treat the application directory as ephemeral and force a clean install every time, eliminating reliance on stale caches.

Implement this sequence for every deployment:

Deployment Artifact Push: Push the application code and composer.json to the server.
Environment Setup: Ensure the runtime environment (Node.js version, dependencies) is explicitly defined and isolated.

Automated Cleanup Script: Before running composer install, execute a cleanup script to remove all previous module states and caches.

#!/bin/bash
        APP_DIR="/var/www/app"
        echo "Cleaning deployment artifacts..."
        rm -rf $APP_DIR/node_modules
        composer clear-cache
        composer install --no-dev --optimize-autoload-files
        echo "Deployment complete."

Restart Configuration: Always restart the Node.js service after running the cleanup script.
```
sudo systemctl restart nodejs-app
```

Conclusion

Debugging production failures is less about finding the broken line of code and more about understanding the environment's state. When facing elusive module errors on an Ubuntu VPS, stop guessing file permissions, and start auditing your build process and dependency caching. Clean slate deployments are the only reliable solution.

asseki hotspot