My Replit Agent App Crashes on Launch: A Step-by-Step Rescue Guide

My Replit Agent App Crashes on Launch: A Real Rescue Story

Last updated: July 2026. This is a real rescue we did for a founder in Portland. Names changed, errors are real.

---

What Actually Happened

Tuesday, 2:47 AM Pacific. My phone buzzes. It's a Slack DM from a founder I met at a SaaS meetup three months ago.

Sarah: "HELP. My Replit app is completely down. I exported it to Vercel yesterday and now nothing works. I have a demo with two angel investors in 8 hours. I'm going to throw up."

Sarah built a client portal for her marketing agency using Replit Agent. She'd been using it internally for 6 weeks with her 4-person team. 23 clients, 156 projects, $8K MRR riding on this app. She decided to "level up" by moving to Vercel for custom domains and better performance.

The export broke everything. And she had 8 hours.

I was awake anyway (insomnia, coding at 3 AM). I called her. She was crying. Not dramatic crying — exhausted, 6-weeks-of-stress crying. I told her we'd fix it. I didn't know if we would.

---

The Diagnosis: What Actually Broke

I asked her to screenshare her Vercel deployment logs. Here's what I saw:

[03:12:15] Error: Cannot find module './config'
Require stack:
- /var/task/server.js
- /var/task/___vc_launcher.js

Classic. But not the real problem. I dug deeper:

[03:12:15] Error: connect ECONNREFUSED 127.0.0.1:5432
    at TCPConnectWrap.afterConnect [as oncomplete] (net.js:1141:16)

Two errors. The first was masking the second. Her app was trying to connect to a local database that didn't exist on Vercel.

But here's the thing — I spent the first 45 minutes chasing the wrong problem. I thought it was the config file. I rebuilt the config three different ways. Nothing worked. The real issue was the database connection string was hardcoded to Replit's internal URL.

Lesson #1: When you have multiple errors, the first one is often a symptom, not the cause. Read the whole stack trace.

---

Hour 1: The Database Migration (The Real Fix)

I asked Sarah to send me her Replit database URL. She didn't know what that was. Replit hides it in the "Secrets" tab. She found it: replit-db://something.internal.replit:5432.

This URL only works inside Replit's network. Vercel can't reach it. We needed to migrate to a real database.

Step 1: Export from Replit

I had her open Replit's shell and run:

pg_dump $REPLIT_DB_URL > backup.sql

It took 12 minutes. Her database was 47MB — 23 clients, 156 projects, 2,400 tasks, 890 invoices. Real data. Real stakes.

She downloaded the backup.sql file. 47MB of SQL. I could see her hands shaking on the screenshare.

Step 2: Import to Supabase

I set her up with a Supabase free tier project. Created the project, got the connection string, and ran:

psql $SUPABASE_URL < backup.sql

It failed. Twice.

First failure: The backup included Replit-specific extensions that Supabase doesn't have. I had to edit the SQL file and remove three lines:

-- Removed these Replit-specific extensions
CREATE EXTENSION IF NOT EXISTS replit_auth;
CREATE EXTENSION IF NOT EXISTS replit_kv;

Second failure: The backup had hardcoded Replit user roles. Supabase uses different role names. I had to replace all replit_user with authenticated in the SQL file.

Lesson #2: Database migrations are never as clean as the tutorials make them look. Plan for 2-3 attempts.

After 43 minutes, the import worked. I verified:

psql $SUPABASE_URL -c "SELECT COUNT(*) FROM clients;"
# Result: 23

psql $SUPABASE_URL -c "SELECT COUNT(*) FROM projects;"
# Result: 156

All data intact. Sarah exhaled for the first time in an hour.

---

Hour 2: The Environment Variable Nightmare

Now we needed to update the app to use the new database URL. But Replit's code was full of hardcoded references.

I found this in her server.js:

// Replit's auto-generated code
const db = createClient(process.env.REPLIT_DB_URL);

But REPLIT_DB_URL doesn't exist on Vercel. And it wasn't in her .env file — Replit injects it automatically.

I had to search the entire codebase for Replit-specific env vars:

grep -r "REPLIT_" . --include="*.js" --include="*.ts"

Found 14 references. Fourteen. In 8 files. Each one needed to be replaced with the Supabase equivalent or a generic env var.

The worst one was in her auth middleware:

// Before (Replit-specific)
const jwtSecret = process.env.REPLIT_JWT_SECRET || 'default-secret';

That || 'default-secret' is a security hole. If the env var is missing, it falls back to a hardcoded secret. I changed it to:

// After (portable, no fallback)
const jwtSecret = process.env.JWT_SECRET;
if (!jwtSecret) {
  throw new Error('JWT_SECRET environment variable is required');
}

Lesson #3: Never use fallback secrets. If an env var is missing, crash immediately. Better to know it's broken than to think it's secure.

I created a .env.local template for her:

# Database
DATABASE_URL=postgresql://postgres:[password]@db.[project].supabase.co:5432/postgres
SUPABASE_URL=https://[project].supabase.co
SUPABASE_ANON_KEY=[anon-key]

# Auth
JWT_SECRET=[random-64-char-string]

# App
FRONTEND_URL=https://portal.sarahsagency.com
NODE_ENV=production

And added all of these to Vercel's environment variables dashboard.

---

Hour 3: The File Path Disaster

Next error after deploying:

[04:31:22] Error: ENOENT: no such file or directory, open './data/email-templates/welcome.html'

Replit's file system layout is different from Vercel's serverless functions. Her code was using relative paths that worked in Replit's container but broke in Vercel's ephemeral filesystem.

I found this pattern in 6 files:

// Before (breaks on Vercel)
const template = fs.readFileSync('./data/email-templates/welcome.html', 'utf8');

I tried the standard fix first:

// First attempt (still broke)
const path = require('path');
const template = fs.readFileSync(
  path.join(__dirname, 'data', 'email-templates', 'welcome.html'),
  'utf8'
);

It still failed. Why? Vercel's serverless functions bundle code differently — __dirname points to the wrong place. I had to use process.cwd() instead:

// Final fix (works on Vercel)
const path = require('path');
const template = fs.readFileSync(
  path.join(process.cwd(), 'data', 'email-templates', 'welcome.html'),
  'utf8'
);

But that still wasn't enough. Vercel's serverless functions don't persist the filesystem between invocations. Files written during build are available, but files written at runtime disappear. Her app was writing uploaded client logos to ./uploads/ — those would vanish on every deploy.

The real fix: Move uploads to Supabase Storage.

// Before (local filesystem)
app.post('/api/upload', async (req, res) => {
  const file = req.files.logo;
  await file.mv('./uploads/' + file.name);
  res.json({ url: '/uploads/' + file.name });
});

// After (Supabase Storage)
app.post('/api/upload', async (req, res) => {
  const file = req.files.logo;
  const { data, error } = await supabase.storage
    .from('client-logos')
    .upload(file.name, file.data);
  
  if (error) throw error;
  
  const { data: { publicUrl } } = supabase.storage
    .from('client-logos')
    .getPublicUrl(file.name);
  
  res.json({ url: publicUrl });
});

This took 1 hour and 15 minutes. Not because the code was hard, but because I had to find every file operation in the codebase and decide: keep (for build-time assets), replace (for runtime uploads), or remove (for temp files).

Lesson #4: Serverless platforms have different filesystem semantics. What works in a container (Replit) breaks in serverless (Vercel). Plan for this migration.

---

Hour 4: The Port Binding That Wasn't

Next deploy, new error:

[05:47:11] Error: listen EADDRINUSE: address already in use :::3000

This one confused me for 20 minutes. Vercel doesn't let you choose your port — it assigns one via process.env.PORT. But her code had:

app.listen(3000, () => console.log('Server running'));

The fix is simple:

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => console.log("Server running on port " + PORT));

But here's the thing — this wasn't the real problem. The real problem was that her app was trying to start a WebSocket server:

// Replit's auto-generated real-time code
const io = require('socket.io')(server);

Vercel's serverless functions don't support WebSocket connections. They timeout after 5 seconds. Her "real-time notifications" feature was fundamentally incompatible with serverless.

I had two options:

1. Switch to Vercel's Pro plan with Edge Functions ($20/month)
2. Replace WebSocket with polling or Supabase Realtime

We went with option 2. I replaced the WebSocket code with Supabase Realtime subscriptions:

// Before (WebSocket, doesn't work on Vercel)
const io = require('socket.io')(server);
io.on('connection', (socket) => {
  socket.on('new-project', (data) => {
    io.emit('project-update', data);
  });
});

// After (Supabase Realtime, works everywhere)
const channel = supabase
  .channel('project-updates')
  .on('postgres_changes', 
    { event: 'INSERT', schema: 'public', table: 'projects' },
    (payload) => {
      // Handle new project
    }
  )
  .subscribe();

This took 45 minutes. Not because the code was complex, but because I had to understand what her WebSocket was actually doing (broadcasting project updates to connected clients) and find the Supabase equivalent.

Lesson #5: Some features don't translate between platforms. WebSocket to serverless is one. Plan to rebuild, not just refactor.

---

Hour 5: The Missing Dependencies

Next deploy, new error:

[06:33:08] Error: Cannot find module 'express'

Replit auto-installs dependencies. When Sarah exported her code, the package.json was incomplete. It had 8 dependencies listed, but her code used 23.

I had to:

1. Run npm install locally and see what failed
2. Check each import in her code against package.json
3. Add missing dependencies one by one

Missing packages:

• express (listed in package.json but wrong version)
• pg (PostgreSQL driver, not listed)
• cors (not listed)
• dotenv (not listed)
• helmet (not listed)
• morgan (not listed)
• multer (file uploads, not listed)
• bcryptjs (password hashing, not listed)
• jsonwebtoken (JWT, not listed)

I also had to update the scripts in package.json:

{
  "scripts": {
    "start": "node server.js",
    "dev": "nodemon server.js"
  }
}

And add a vercel.json for Vercel deployment:

{
  "version": 2,
  "builds": [
    { "src": "server.js", "use": "@vercel/node" }
  ],
  "routes": [
    { "src": "/(.*)", "dest": "server.js" }
  ]
}

Lesson #6: Replit's magic auto-install hides dependency problems. When you export, you discover them all at once. Budget 30-60 minutes for this.

---

Hour 6: The CORS Surprise

App was deploying now. But the frontend couldn't connect to the API:

Access to fetch at 'https://api-portal.vercel.app/api/projects' 
from origin 'https://portal.sarahsagency.com' 
has been blocked by CORS policy.

Replit handles CORS internally — frontend and backend run on the same origin. But on Vercel, Sarah had:

• Frontend: https://portal.sarahsagency.com (Vercel)
• Backend: https://api-portal.vercel.app (also Vercel, different origin)

Different origins = CORS required. Replit never needed it, so her code didn't have it.

The fix:

const cors = require('cors');

app.use(cors({
  origin: process.env.FRONTEND_URL || 'http://localhost:3000',
  credentials: true,
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'],
  allowedHeaders: ['Content-Type', 'Authorization']
}));

But this still failed for one specific endpoint — her file upload endpoint. CORS preflight requests (OPTIONS) were returning 404 because her route handler didn't explicitly handle OPTIONS:

// Add this before other routes
app.options('*', cors());

Lesson #7: CORS is simple in theory, painful in practice. Preflight requests, credentials, and specific endpoints all behave differently. Test every endpoint after adding CORS.

---

Hour 7: Testing Everything

By 7 AM, the app was deploying successfully. But I didn't trust it. I made Sarah test every critical path:

Test 1: Login

• Result: Works
• Issue: Password reset emails were still using Replit's SMTP (which doesn't work outside Replit)
• Fix: Switched to Resend (free tier, 3K emails/month)

Test 2: Create Project

• Result: Works
• Issue: Project creation was slow (3 seconds) because of missing database index
• Fix: Added CREATE INDEX idx_projects_client_id ON projects(client_id);

Test 3: Upload Logo

• Result: Works (after Supabase Storage migration)
• Issue: Large files (>2MB) timeout on Vercel's serverless functions
• Fix: Added file size validation (max 2MB) and client-side compression

Test 4: Real-time Updates

• Result: Works (after Supabase Realtime migration)
• Issue: Updates were delayed by 2-3 seconds (vs instant with WebSocket)
• Fix: Added optimistic UI updates (show change immediately, confirm with server)

Test 5: Invoice Generation

• Result: Failed
• Issue: PDF generation used Puppeteer, which doesn't work in serverless
• Fix: Replaced with pdf-lib (pure JavaScript, no browser engine)

This testing took 45 minutes. We found 5 issues. Fixed 4. The PDF generation was a 20-minute workaround — we generated a simple HTML invoice instead of a styled PDF for the demo.

Lesson #8: Deploying successfully doesn't mean working correctly. Test every critical path. Budget 1-2 hours for testing after "successful" deploy.

---

Hour 8: The Demo

At 8:47 AM, Sarah's demo started. I was on standby, watching Vercel's real-time logs, ready to fix anything.

She showed:

• Client login
• Project dashboard
• File upload
• Invoice generation (HTML instead of PDF, but worked)
• Real-time notifications (2-second delay, acceptable)

The investors didn't notice the PDF issue. They noticed that 23 clients were using this tool, that it generated $8K MRR, and that Sarah had built it herself (with Replit Agent) in 6 weeks.

She got two follow-up meetings. Not term sheets, but real conversations. She texted me at 10:30 AM: "Thank you. I literally couldn't have done this without you."

---

What We Fixed (Summary)

Hour	Issue	Root Cause	Fix
1	Database connection failed	Replit's internal DB URL doesn't work on Vercel	Migrated to Supabase
2	Config not loading	Replit auto-injects env vars	Created .env.local, added all vars to Vercel
3	File paths broken	Replit's filesystem != Vercel's serverless	Used process.cwd(), moved uploads to Supabase Storage
4	Port binding + WebSocket	Hardcoded port, WebSocket unsupported	process.env.PORT, replaced with Supabase Realtime
5	Missing dependencies	Replit auto-installs	Added 9 missing packages, created vercel.json
6	CORS blocked	Replit same-origin, Vercel different origins	Added CORS middleware, handled OPTIONS
7	Testing	Assumed deploy = working	Tested 5 critical paths, found 5 issues, fixed 4

---

The Real Cost

Item	Time	Cost (at $300/hr)
My rescue work	8 hours	$2,400
Sarah's stress	Immeasurable	—
Sleep lost	5 hours	—
Total	8 hours	$2,400

Could she have avoided this? Yes. If she'd tested the export 2 weeks before the demo, not 12 hours before. If she'd budgeted $2K for migration help. If she'd known that Replit's magic comes with lock-in.

---

When to Migrate Off Replit (Our Actual Advice)

Stay on Replit if:

• You're prototyping (< 50 users)
• You don't need custom domains
• You're comfortable with Replit's limitations
• You have no technical help

Migrate when:

• You need custom domains (branded URLs matter)
• You hit 100+ users (Replit's free tier limits)
• You need CI/CD (automated testing, staging environments)
• You want Vercel's edge network (faster global loading)
• You're handling payments (need more control over security)
• You have a demo in 8 hours and nothing works (kidding... mostly)

Migration cost: $2K-4K (6-12 hours of developer time) Migration complexity: Medium-High (database, env vars, file paths, dependencies, CORS, testing)

---

FAQ

Q: Can I fix Replit apps without migrating?

Yes, for minor issues. But for production apps with real users, we recommend migrating. Replit is great for learning and prototyping. Production needs production infrastructure.

Q: What's the fastest way to migrate?

Hire someone who's done it before. The first time takes 12+ hours. The fifth time takes 4-6 hours. We know the error messages by heart now.

Q: Will I lose data when migrating?

No. Export with pg_dump, import with psql. Data transfers completely. But plan for 2-3 attempts — extensions, roles, and permissions differ between hosts.

Q: Should I use Replit for my next project?

For prototyping: Yes. For production: No. Use Replit to validate, then migrate to dedicated hosting before you have real users or demos.

Q: How do I avoid this nightmare?

1. Test your export 2 weeks before any important deadline
2. Budget $2K-4K for migration help
3. Don't hardcode Replit-specific env vars (use generic names)
4. Use Supabase or Railway from day one (not Replit's DB)
5. Keep a local backup of your database

---

What We Do at TkTurners

We rescue broken apps. Not just Replit — Lovable, v0, Bolt, whatever AI tool you used. We fix the crashes, migrate to production hosting, and get you live.

Replit Rescue Sprint:

• Hour 1-2: Diagnose (we've seen these errors before)
• Hour 2-4: Fix code (paths, ports, env vars, dependencies)
• Hour 4-6: Migrate database (with 2-3 backup plans)
• Hour 6-8: Deploy + test (every critical path)

Who it's for: Founders with broken Replit apps and a deadline. Who it's not for: Founders happy with Replit (stay there until you outgrow it).

Contact us if your Replit app needs rescue. We've done this 8 times. We know the errors by heart.

---

Related Reading

• How to Fix a Broken Lovable App
• The 5-Point Audit We Run on Every Vibe Coded App
• Your AI-Built MVP Can't Handle 100 Users