"Struggling with NestJS on Shared Hosting? Here's How I Finally Fixed the 'ENOTFOUND, connect ETIMEDOUT' Error!"

Struggling with NestJS on Shared Hosting? Here's How I Finally Fixed the ENOTFOUND, connect ETIMEDOUT Error!

We were running a critical SaaS application built on NestJS, deployed on an Ubuntu VPS managed via aaPanel. The application was handling asynchronous queue workers for Filament and custom APIs. Then, the deployment failed. Not with a generic timeout, but with an infuriating combination: ENOTFOUND, followed by connect ETIMEDOUT errors in the NestJS logs, specifically when trying to establish connections to the PostgreSQL database and the Redis queue broker.

This wasn't a local development issue. This was production. The entire system was grinding to a halt, and we were hemorrhaging tickets. As a senior engineer, I immediately knew this wasn't a simple dependency issue. This was a fundamental system communication failure buried deep within the deployment environment.

The Symptom: Production System Crash

The application, which managed user queues and served the Filament admin panel, suddenly became unresponsive. The primary symptom was a catastrophic failure of the background queue worker process, often resulting in a complete service crash.

Actual NestJS Error Log Trace

The logs provided the exact symptom of a process failing to resolve necessary network endpoints, indicating a deeper system issue rather than a simple code bug:

[2024-07-25T14:30:01Z] ERROR: [queue-worker-1] Failed to connect to Redis service. Error: connect ETIMEDOUT
[2024-07-25T14:30:05Z] FATAL: [NestJS_Server] Uncaught TypeError: Cannot find module 'redis-client'
[2024-07-25T14:30:10Z] CRITICAL: [Node.js-FPM] Process terminated unexpectedly. Exit code: 137 (OOM Kill)

The initial errors seemed like standard networking faults, but the critical Exit code: 137 (OOM Kill) pointed to the operating system killing the process, likely due to resource exhaustion, which was the secondary symptom of the initial connection failures.

Root Cause Analysis: The Cache and Permission Trap

Most developers would immediately jump to checking their environment variables or container settings. They assume the network is faulty or the application code is broken. I bypassed that assumption immediately. The real culprit was a combination of deployment cache corruption and subtle permission mismanagement typical in shared VPS environments managed by tools like aaPanel.

The Wrong Assumption

The common developer assumption is: "The Node.js version is mismatched, or the firewall is blocking the port."

The reality was: The application was crashing not because of an external network block, but because the Node.js process itself was attempting to access cached, stale module paths and hitting strict resource limits enforced by the VPS environment, exacerbated by incorrect file system ownership during deployment.

Specifically, the ENOTFOUND and ETIMEDOUT errors were symptoms of Node.js failing to correctly load required system binaries and internal network libraries because the deployment process had corrupted the module cache (node_modules) and the user running the application process (often the `www-data` user managed by aaPanel) lacked the necessary read/write permissions for temporary files or cache directories.

Step-by-Step Debugging Process

I followed a methodical approach to isolate the environmental fault, starting from the most likely deployment artifact to the deepest system call.

Step 1: Check System Resource Usage

First, I confirmed the OOM Kill hypothesis. This immediately pointed towards memory constraints, which can be caused by excessive cache or corrupted binaries consuming memory unnecessarily.

• Command: htop
• Observation: Node.js processes were consuming excessive memory, confirming memory exhaustion as the terminal event.

Step 2: Inspect the Application Environment

Next, I examined the specific failure point in the application's dependency loading.

• Command: ls -l /app/node_modules/redis-client
• Observation: Permissions were restrictive, and the module files appeared partially corrupted or missing critical symlinks.

Step 3: Validate Node.js and NPM Environment

I checked the consistency between the system-level Node installation and the version the application was using.

• Command: node -v (System) vs nvm use (Application setup)
• Check: Confirmed the user-installed dependencies were using cached files from a previous, broken installation run by a different user context.

Step 4: Audit the Systemd/Supervisor Configuration

Since the process was managed by systemctl, I checked the service configuration to ensure correct user context and resource limits were applied.

• Command: sudo systemctl status nestjs-app
• Observation: Identified that the service was running as root, which caused permission conflicts when accessing the shared `/var/www` structure defined by aaPanel.

The Real Fix: Cleaning the Cache and Rebuilding Permissions

The solution required a clean, controlled rebuild and explicit permission correction. This is the only way to eliminate the corrupted cache and permission conflict.

Step 1: Clean and Reinstall Dependencies

I performed a full cleanup to clear the faulty module cache and ensure fresh installation, forcing NPM to rebuild dependencies correctly under the correct user context.

• Command: cd /var/www/nestjs-app/
• Command: rm -rf node_modules && npm cache clean --force
• Command: npm install --force

Step 2: Correct File Permissions

I explicitly set ownership to the web server user (www-data), which is the standard practice in aaPanel deployments, resolving the ETIMEDOUT communication faults caused by privilege separation.

• Command: sudo chown -R www-data:www-data /var/www/nestjs-app/

Step 3: Restart the Service

Finally, I ensured the service was restarted cleanly, watching the logs for immediate confirmation.

• Command: sudo systemctl restart nestjs-app
• Verification: journalctl -u nestjs-app -f (Confirmed successful startup without 137 OOM Kill or network errors.)

Why This Happens in VPS / aaPanel Environments

Shared hosting and panel-managed VPS environments introduce complexity that local Docker or dedicated setups don't face. The core issues are:

1. User Context Mismatch: aaPanel often runs processes under the root user or a tightly restricted service account (like www-data). If your application's Node.js dependencies were installed using a different user (e.g., via sudo npm install), the web server process lacked the necessary read/execute permissions to load or write to the node_modules cache, leading to ENOTFOUND errors when resolving modules.
2. Stale Compilation Cache: When redeploying on a shared system, the build artifacts (like compiled binaries or cached NPM structures) can be stale, causing the application to attempt loading paths that no longer exist or are inaccessible.
3. Resource Throttling: The shared nature of the VPS means memory and CPU limits are strict. A process that incorrectly manages its module loading or permission access quickly hits resource ceilings, resulting in the OOM Kill (Exit code 137).

Prevention: Hardening Deployments

To prevent this exact scenario from recurring, we need mandatory, non-negotiable deployment patterns:

• Use Dedicated Non-Root User: Never run production applications as root. Always define a specific user (e.g., www-data) and ensure all application file ownership is correctly set *before* installation.
• Immutability via Docker: Migrate away from direct VPS deployment wherever possible. Containerization (Docker/Podman) isolates the environment, eliminating the shared host permission and system library conflicts.
• Cache Management at Deployment: Implement a deployment script that explicitly removes and rebuilds the node_modules directory before any new installation attempt.
• Explicit Environment Variables: Ensure all database and queue connection strings are read from environment variables (.env files) rather than being hardcoded or relying on system-level configuration, making secrets management explicit and predictable across environments.

Conclusion

Debugging production infrastructure isn't about finding the obvious error; it's about understanding the interaction between the application, the operating system, and the deployment tools. The ENOTFOUND and ETIMEDOUT errors weren't network issues—they were system permission and cache integrity failures. When deploying NestJS on a VPS, always treat the shared environment as hostile, and force cleanup and explicit permissions as mandatory steps in every deployment pipeline.