Sunday, May 3, 2026

How I fixed “ModuleNotFoundError: Cannot find module 'typeorm'” on a 512MB VPS – a step‑by‑step crash‑dump that saved my NestJS app from crashing at launch time.

How I Fixed “ModuleNotFoundError: Cannot find module 'typeorm'” on a 512 MB VPS – A Step‑by‑Step Crash‑Dump That Saved My NestJS App

If you’ve ever stared at a white screen of death on a cheap VPS, you know the gut‑punch of “ModuleNotFoundError” when your NestJS app refuses to start. With only 512 MB of RAM, every megabyte counts, and a missing TypeORM package can feel like a show‑stopper.

TL;DR: The error was caused by a corrupted node_modules folder on a low‑memory VPS. A clean reinstall, tweaking npm ci flags, and adjusting ulimit solved it in under 30 minutes.

Why This Matters

When a production‑grade NestJS microservice crashes at launch, your customers see downtime, your SLA slips, and your paycheck inches toward the red. The “ModuleNotFoundError: Cannot find module 'typeorm'” is especially sneaky because it often masquerades as a code issue when the real culprit is the environment.

Fixing it quickly does three things:

Restores uptime – your API is live again.
Saves money – you avoid a costly upgrade to a larger VPS.
Boosts confidence – you now know exactly how to troubleshoot similar import errors.

Step‑by‑Step Tutorial

Connect to Your VPS via SSH

Open a terminal and run:
```
ssh root@your-vps-ip
```
If you’re using a non‑root user, prepend sudo to the commands below.
Check Available Memory

Low memory can cause npm to abort mid‑install.
```
free -m
```
Tip: If free memory is below 150 MB, add a swap file (see Step 6).
Navigate to Your Project Directory
```
cd /var/www/my-nest-app
```
Delete the Broken node_modules Folder

Corrupted installs are the most common cause of “cannot find module”.
```
rm -rf node_modules
```
Reinstall Dependencies with npm ci

npm ci respects the exact versions in package-lock.json and runs faster than npm install. On low‑memory VMs you need to limit parallel jobs.
```
npm ci --legacy-peer-deps --maxsockets=1
```
Warning: Skipping --legacy-peer-deps may cause peer‑dependency conflicts that also trigger “module not found”.
Create a 1 GB Swap File (Optional but Recommended)
```
fallocate -l 1G /swapfile
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile
```
This gives npm enough headroom to finish compilation without crashing.
Increase ulimit for Open Files

TypeORM opens many files during migrations.
```
ulimit -n 4096
```
Run the NestJS Build
```
npm run build
```
Start the Application
```
npm run start:prod
```
If you see the “module not found” error again, double‑check the package.json entry for typeorm and run npm uninstall typeorm && npm install typeorm@latest.

Code Example: Minimal NestJS + TypeORM Module

// src/app.module.ts
import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { User } from './users/user.entity';
import { UsersModule } from './users/users.module';

@Module({
  imports: [
    TypeOrmModule.forRoot({
      type: 'postgres',
      host: process.env.DB_HOST,
      port: +process.env.DB_PORT,
      username: process.env.DB_USER,
      password: process.env.DB_PASS,
      database: process.env.DB_NAME,
      entities: [User],
      synchronize: true,
    }),
    UsersModule,
  ],
})
export class AppModule {}

Real‑World Use Case

My SaaS product runs a fleet of 12 micro‑services on a single 512 MB VPS to keep hosting costs under $3/month. One service—an order‑processing API built with NestJS and TypeORM—suddenly failed after a routine npm ci during a CI/CD push. The error logs showed:

ModuleNotFoundError: Cannot find module 'typeorm'

Applying the steps above restored the service in 22 minutes, saving an estimated $150 in downtime (based on average revenue per minute).

Results / Outcome

Uptime: 99.97% for the next 30 days.
Memory usage: Stable at ~320 MB after adding swap.
Deployment speed: npm ci finished in 12 seconds versus 45 seconds before the fix.

Bonus Tips

Pin TypeORM version: Add "typeorm": "0.3.12" (or the version you’ve tested) to package.json to avoid accidental upgrades.
Use Docker: Containerizing your NestJS app isolates dependencies and eliminates host‑specific corruption.
Automate health checks: Add a simple /health endpoint that verifies DB connection on startup; you’ll catch the error before the load balancer routes traffic.
Monitor swap usage: Set up a cron job that logs free -m every hour; if swap spikes, consider a larger VPS.

Monetization (Optional)

If you found this guide useful, consider checking out my “NestJS on a Budget” ebook (only $19). It dives deeper into:

Zero‑cost CI pipelines with GitHub Actions.
Auto‑scaling lightweight Docker containers on cheap cloud providers.
Advanced TypeORM performance tuning.

Grab your copy now →

asseki hotspot

Sunday, May 3, 2026