Replit Common Errors

Overview

Quick reference for the 10 most common Replit errors with real solutions. Covers container lifecycle, Nix configuration, database, deployment, and networking issues.

Prerequisites

• Replit Workspace access
• Shell tab for diagnostics
• Console tab for error logs

Error Reference

1. Container Sleeping / App Goes Offline

Error: Your Repl is sleeping. Run it to wake up.

Cause: Free/Hacker plan Repls sleep after ~5 minutes of inactivity.

Solution:

• Use Replit Deployments (Autoscale or Reserved VM) for always-on
• Or set up external keep-alive pinging (UptimeRobot, cron-job.org)
• Check: Settings > Always On (deprecated in favor of Deployments)

2. Port Binding / Webview Not Loading

Error: EADDRINUSE: address already in use :::3000

Cause: Previous process still holding the port, or hardcoded port conflicts.

Solution:

# Find and kill the process
lsof -i :3000 | grep LISTEN
kill -9 <PID>

# Or use environment variable for port

// Always use PORT env var
const port = parseInt(process.env.PORT || '3000');
app.listen(port, '0.0.0.0');  // Must be 0.0.0.0, not localhost

3. Nix Package Build Failure

Error: error: Package 'python-xyz' not found in channel 'stable-23_05'

Cause: Package name wrong, or Nix channel too old.

Solution:

# replit.nix — update channel and fix package names
{ pkgs }: {
  deps = [
    pkgs.nodejs-20_x          # not "nodejs" or "node"
    pkgs.python311             # not "python3" or "python"
    pkgs.python311Packages.pip # not "pip"
    pkgs.zlib                  # for native modules (Pillow, etc.)
    pkgs.openssl               # for crypto dependencies
  ];
}

# .replit — use current stable channel
[nix]
channel = "stable-24_05"

After editing replit.nix, reload the shell (exit and re-enter Shell tab).

4. DATABASE_URL Not Set

Error: Connection refused / ECONNREFUSED / DATABASE_URL is undefined

Cause: PostgreSQL not provisioned, or accessing outside Replit.

Solution:

1. Open the Database pane in the sidebar
2. Click "Create a database" if none exists
3. DATABASE_URL auto-populates in your environment
4. For legacy Replit DB: check REPLITDBURL instead

5. Replit DB Write Failure (50MB Limit)

Replit Core Workflow B — Teams & Admin

Overview

Secondary workflow for Replit: team member management, role assignment, deployment promotion (dev to production), custom domain setup, and organizational audit. Complements the app-building workflow in replit-core-workflow-a.

Prerequisites

• Replit Teams or Enterprise plan
• Organization Owner or Admin role
• Team API token stored in REPLIT_TOKEN

Instructions

Step 1: Team Member Management

// src/admin/team-manager.ts
interface TeamMember {
  username: string;
  email: string;
  role: 'owner' | 'admin' | 'member';
  lastActive: string;
}

async function listMembers(teamId: string): Promise<TeamMember[]> {
  const res = await fetch(`https://replit.com/api/v1/teams/${teamId}/members`, {
    headers: { Authorization: `Bearer ${process.env.REPLIT_TOKEN}` },
  });
  return res.json();
}

async function inviteMember(teamId: string, email: string, role: string) {
  return fetch(`https://replit.com/api/v1/teams/${teamId}/members`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.REPLIT_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ email, role }),
  });
}

async function removeMember(teamId: string, username: string) {
  return fetch(`https://replit.com/api/v1/teams/${teamId}/members/${username}`, {
    method: 'DELETE',
    headers: { Authorization: `Bearer ${process.env.REPLIT_TOKEN}` },
  });
}

Step 2: Seat Audit

// Identify inactive members for seat optimization
async function auditSeats(teamId: string) {
  const members = await listMembers(teamId);
  const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);

  const audit = {
    total: members.length,
    active: members.filter(m => new Date(m.lastActive) > thirtyDaysAgo),
    inactive: members.filter(m => new Date(m.lastActive) <= thirtyDaysAgo),
    costPerSeat: 25, // USD/month for Teams
  };

  console.log(`Active: ${audit.active.length}, Inactive: ${audit.inactive.length}`);
  console.log(`Potential savings: $${audit.inactive.length * audit.costPerSeat}/month`);

  return audit;
}

Step 3: Deployment Promotion

// Promote from development to production deployment
async function promoteDeployment(replId: string) {
  // Step 1: Verify dev deployment is healthy
  const devHealth = await fetch(`https://${replId}.replit.dev/health`);
  if (!devHealth.ok) {
    throw new Error('Development deployment not healthy. Fix before promoting.');
  }

  // Step 2: Trigger production deployment
  const res = await fetch(`https://replit.com/api/v1/repls/${replId}/deploy`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${p

Replit Cost Tuning

Overview

Optimize Replit spending across deployment compute, seat licenses, egress, and storage. Covers right-sizing deployment resources, choosing between Autoscale and Reserved VM, eliminating idle Repls, and managing team seat costs.

Prerequisites

• Replit account with billing access
• Understanding of current deployment architecture
• Access to usage metrics in Replit dashboard

Replit Pricing Model

Instructions

Step 1: Audit Deployment Costs

Review what you're spending and where:

In Replit Dashboard > Billing:
1. View "Usage" tab for compute breakdown
2. Sort by cost to find expensive Repls
3. Check "Always On" Repls (legacy) — convert to Deployments

Key metrics to check:
- CPU hours consumed per Repl
- Memory-hours consumed per Repl
- Egress data transfer per Repl
- Number of cold starts (Autoscale)

Step 2: Right-Size Deployment Resources

# Match resources to actual workload

micro:  # Simple bot, webhook receiver
  type: autoscale
  cost: "Pay per request (free when idle)"
  best_for: "< 1000 requests/day, tolerates cold starts"

small:  # Basic API or web app
  type: reserved_vm
  cpu: 0.25 vCPU
  memory: 512 MB
  cost: "~$6/month"
  best_for: "Low traffic, always-on required"

medium:  # Production web app
  type: reserved_vm
  cpu: 0.5 vCPU
  memory: 1 GB
  cost: "~$12/month"
  best_for: "Standard traffic, good response times"

large:  # Compute-heavy or high-traffic
  type: reserved_vm
  cpu: 2 vCPU
  memory: 4 GB
  cost: "~$40/month"
  best_for: "High traffic, background processing"

# Rule of thumb: if peak CPU < 30% and peak memory < 50%, downsize

Step 3: Choose Autoscale vs Reserved VM

Use AUTOSCALE when:
- Traffic is unpredictable or bursty
- App can tolerate 5-15s cold starts
- Many hours of zero traffic per day
- Low daily request count (< 5000)
- Cost: $0 when idle, proportional t

Replit Data Handling

Overview

Manage application data securely across Replit's three storage systems: PostgreSQL (relational), Key-Value Database (simple cache/state), and Object Storage (files/blobs). Covers connection patterns, security, data validation, and choosing the right storage for each use case.

Prerequisites

• Replit account with Workspace access
• PostgreSQL provisioned in Database pane (for SQL use cases)
• Understanding of Replit Secrets for credentials

Storage Decision Matrix

Instructions

Step 1: PostgreSQL — Secure Connection

// src/services/database.ts
import { Pool, PoolConfig } from 'pg';

function createPool(): Pool {
  if (!process.env.DATABASE_URL) {
    throw new Error('DATABASE_URL not set. Create a database in the Database pane.');
  }

  const config: PoolConfig = {
    connectionString: process.env.DATABASE_URL,
    ssl: { rejectUnauthorized: false }, // Required for Replit PostgreSQL
    max: 10,
    idleTimeoutMillis: 30000,
    connectionTimeoutMillis: 5000,
  };

  const pool = new Pool(config);

  // Log errors without exposing connection string
  pool.on('error', (err) => {
    console.error('Database pool error:', err.message);
    // Never: console.error(err) — may contain credentials
  });

  return pool;
}

export const pool = createPool();

// Parameterized queries ONLY — never string concatenation
export async function findUser(userId: string) {
  // GOOD: parameterized
  const result = await pool.query(
    'SELECT id, username, created_at FROM users WHERE id = $1',
    [userId]
  );
  return result.rows[0];

  // BAD: SQL injection risk
  // pool.query(`SELECT * FROM users WHERE id = '${userId}'`)
}

Dev vs Production databases:

Replit auto-provisions separate databases:
- Development: used when running in Workspace ("Run" button)
- Production: used when accessed via deployment URL

View in Database pane:
- Development tab: test data, iterate freely
- Production tab: live customer data, handle with care

Both use the same DATABASE_URL — Replit routes automatically.

Step 2: Key-Value Database — Session & Cache

Node.js:

// src/s

Replit Debug Bundle

Current State

!node --version 2>/dev/null || echo 'Node: N/A'

!python3 --version 2>/dev/null || echo 'Python: N/A'

!echo "REPLSLUG=$REPLSLUG REPLOWNER=$REPLOWNER" 2>/dev/null || echo 'Not on Replit'

Overview

Collect all diagnostic information needed to debug Replit workspace, deployment, and database issues. Produces a redacted evidence bundle safe for sharing with Replit support.

Prerequisites

• Shell access in Replit Workspace
• Permission to read logs and configuration
• Access to deployment monitoring (if deployed)

Instructions

Step 1: Automated Debug Bundle Script

#!/bin/bash
set -euo pipefail
# replit-debug-bundle.sh

BUNDLE="replit-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE"/{env,db,config,network,packages}

echo "=== Replit Debug Bundle ===" > "$BUNDLE/summary.txt"
echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$BUNDLE/summary.txt"
echo "" >> "$BUNDLE/summary.txt"

# 1. Environment info
echo "--- Runtime ---" >> "$BUNDLE/env/runtime.txt"
node --version >> "$BUNDLE/env/runtime.txt" 2>&1 || echo "Node: N/A" >> "$BUNDLE/env/runtime.txt"
python3 --version >> "$BUNDLE/env/runtime.txt" 2>&1 || echo "Python: N/A" >> "$BUNDLE/env/runtime.txt"
uname -a >> "$BUNDLE/env/runtime.txt"

# 2. Replit environment variables (safe ones only)
echo "--- Replit Env ---" >> "$BUNDLE/env/replit-vars.txt"
echo "REPL_SLUG=$REPL_SLUG" >> "$BUNDLE/env/replit-vars.txt"
echo "REPL_OWNER=$REPL_OWNER" >> "$BUNDLE/env/replit-vars.txt"
echo "REPL_ID=$REPL_ID" >> "$BUNDLE/env/replit-vars.txt"
echo "REPLIT_DB_URL=${REPLIT_DB_URL:+SET}" >> "$BUNDLE/env/replit-vars.txt"
echo "DATABASE_URL=${DATABASE_URL:+SET}" >> "$BUNDLE/env/replit-vars.txt"
echo "NODE_ENV=${NODE_ENV:-unset}" >> "$BUNDLE/env/replit-vars.txt"

# 3. Package versions
npm list --depth=0 > "$BUNDLE/packages/npm.txt" 2>&1 || true
pip list > "$BUNDLE/packages/pip.txt" 2>&1 || true

# 4. Configuration files (redacted)
cp .replit "$BUNDLE/config/.replit" 2>/dev/null || echo "No .replit" > "$BUNDLE/config/.replit"
cp replit.nix "$BUNDLE/config/replit.nix" 2>/dev/null || echo "No replit.nix" > "$BUNDLE/config/replit.nix"

# 5. Database connectivity
echo "--- Database ---" >> "$BUNDLE/db/status.txt"
if [ -n "${DATABASE_URL:-}" ]; then
  ec

Replit Deploy Integration

Overview

Deploy applications on Replit's hosting platform. Three deployment types: Static (free, frontend-only), Autoscale (scales to zero, pay per request), and Reserved VM (always-on, fixed cost). Includes custom domain setup, health checks, rollbacks, and deployment monitoring.

Prerequisites

• Replit Core, Pro, or Teams plan (deployment access)
• Application working in Workspace ("Run" button)
• Custom domain (optional) with DNS access

Deployment Types

Instructions

Step 1: Configure .replit for Deployment

# .replit — Autoscale deployment (most common)
entrypoint = "src/index.ts"
run = "npx tsx src/index.ts"

[nix]
channel = "stable-24_05"

[env]
NODE_ENV = "production"

[deployment]
run = ["sh", "-c", "npx tsx src/index.ts"]
build = ["sh", "-c", "npm ci --production && npm run build"]
deploymentTarget = "autoscale"

Reserved VM:

[deployment]
run = ["sh", "-c", "node dist/index.js"]
build = ["sh", "-c", "npm ci && npm run build"]
deploymentTarget = "cloudrun"

Static:

[deployment]
deploymentTarget = "static"
publicDir = "dist"
build = ["sh", "-c", "npm ci && npm run build"]

Step 2: Configure Secrets for Production

Workspace Secrets auto-sync to Deployments (2025+).

1. Click lock icon (Secrets) in sidebar
2. Add production secrets:
   - DATABASE_URL (auto-populated by Replit PostgreSQL)
   - API_KEY, JWT_SECRET, etc.
3. Verify in Deployment Settings > Environment Variables

Step 3: Add Health Check Endpoint

Replit monitors your deployment via health checks. Always include one:

// src/routes/health.ts
import { Router } from 'express';
import { pool } from '../services/db';

const router = Router();

router.get('/health', async (req, res) => {
  const checks: Record<string, any> = {
    status: 'ok',
    uptime: process.uptime(),
    timestamp: new Date().toISOString()

Replit Enterprise RBAC

Overview

Manage team access to Replit workspaces, deployments, and AI features. Covers the built-in role system (Admin, Manager, Editor, Viewer), custom groups (Enterprise only), SSO/SAML integration, deployment permissions, and audit logging.

Prerequisites

• Replit Teams or Enterprise plan
• Organization Owner or Admin role
• SSO identity provider (Enterprise only): Okta, Azure AD, Google Workspace

Role Hierarchy

Instructions

Step 1: Configure Organization Roles

In Organization Settings > Members:

1. Invite members:
   - Click "Invite" > enter email
   - Select role: Admin, Manager, Editor, or Viewer
   - Member receives email invitation

2. Bulk management (2025+):
   - CSV export of all members
   - Sort/filter by role, activity, last login
   - Bulk role changes

3. Role assignment strategy:
   - Owners: 1-2 (billing + full admin)
   - Admins: team leads (manage members + deploy)
   - Managers: senior devs (deploy to staging)
   - Editors: developers (create + code)
   - Viewers: stakeholders (read-only access)

Step 2: Custom Groups (Enterprise Only)

Enterprise plan enables custom permission groups:

1. Organization Settings > Groups
2. Create group: e.g., "Backend Team"
3. Assign permissions:
   - Access to specific Repls
   - Deployment permissions (staging only, or all)
   - AI feature access
4. Add members to group

Example groups:
- "Frontend Team": access to UI Repls, deploy to staging
- "DevOps": all Repls, deploy to production, manage secrets
- "Contractors": specific Repls only, no deployment access
- "QA": read all, deploy to staging, no production

Step 3: SSO/SAML Configuration (Enterprise Only)

Organization Settings > Security > SSO:

1. Choose provider:
   - Okta
   - Azure Active Directory
   - Google Workspace
   - Any SAML 2.0 compatible IdP

2. Configure SAML:
   - ACS URL: provided by Replit
   - Entity ID: provided by Replit
   - Certificate: from your IdP
   - Map IdP groups to Repli

Replit Hello World

Overview

Build a working Replit app that demonstrates core platform services: Express/Flask server, Replit Database (key-value store), Object Storage (file uploads), Auth (user login), and PostgreSQL. Produces a running app you can deploy.

Prerequisites

• Replit App created (template or blank)
• .replit and replit.nix configured (see replit-install-auth)
• Node.js 18+ or Python 3.10+

Instructions

Step 1: Node.js — Express + Replit Database

// index.ts
import express from 'express';
import Database from '@replit/database';

const app = express();
const db = new Database();
app.use(express.json());

// Health check with Replit env vars
app.get('/health', (req, res) => {
  res.json({
    status: 'ok',
    repl: process.env.REPL_SLUG,
    owner: process.env.REPL_OWNER,
    timestamp: new Date().toISOString(),
  });
});

// Replit Key-Value Database CRUD
// Limits: 50 MiB total, 5,000 keys, 1 KB per key, 5 MiB per value
app.post('/api/items', async (req, res) => {
  const { key, value } = req.body;
  await db.set(key, value);
  res.json({ stored: key });
});

app.get('/api/items/:key', async (req, res) => {
  const value = await db.get(req.params.key);
  if (value === null) return res.status(404).json({ error: 'Not found' });
  res.json({ key: req.params.key, value });
});

app.get('/api/items', async (req, res) => {
  const prefix = (req.query.prefix as string) || '';
  const keys = await db.list(prefix);
  res.json({ keys });
});

app.delete('/api/items/:key', async (req, res) => {
  await db.delete(req.params.key);
  res.json({ deleted: req.params.key });
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
  console.log(`Repl: ${process.env.REPL_SLUG} by ${process.env.REPL_OWNER}`);
});

package.json dependencies:

{
  "dependencies": {
    "@replit/database": "^2.0.0",
    "express": "^4.18.0"
  },
  "devDependencies": {
    "@types/express": "^4.17.0",
    "typescript": "^5.0.0"
  }
}

Step 2: Python — Flask + Replit Database

# main.py
from flask import Flask, request, jsonify
from replit import db
import os

app = Flask(__name__)

@app.route('/health')
def health():
    return jsonify({
        'status': 'ok',
        'repl': os.environ.get('REPL_SLUG'),
        'owner': os.environ.get('REPL_OWNER'),
    })

# Replit DB works like a Python dict
@app.route('/api/items', methods=['POST'])
def create_item():
    data = request.js

Replit Incident Runbook

Overview

Rapid incident response for Replit deployment failures, database issues, and platform outages. Covers triage, diagnosis, remediation, rollback, and communication.

Prerequisites

• Access to Replit Workspace and Deployment settings
• Deployment URL for health checks
• Communication channel (Slack, email)
• Rollback awareness (Deployment History)

Severity Levels

Quick Triage (First 5 Minutes)

set -euo pipefail
DEPLOY_URL="https://your-app.replit.app"

echo "=== TRIAGE ==="

# 1. Check Replit platform status
echo -n "Replit Status: "
curl -s https://status.replit.com/api/v2/summary.json | \
  python3 -c "import sys,json;print(json.load(sys.stdin)['status']['description'])" 2>/dev/null || \
  echo "Check https://status.replit.com"

# 2. Check your deployment health
echo -n "App Health: "
curl -s -o /dev/null -w "HTTP %{http_code} (%{time_total}s)" "$DEPLOY_URL/health" 2>/dev/null || echo "UNREACHABLE"
echo ""

# 3. Get health details
echo "Health Response:"
curl -s "$DEPLOY_URL/health" 2>/dev/null | python3 -m json.tool 2>/dev/null || echo "No response"

# 4. Check if it's a cold start issue (Autoscale)
echo -n "Second request: "
curl -s -o /dev/null -w "HTTP %{http_code} (%{time_total}s)\n" "$DEPLOY_URL/health"

Decision Tree

App not responding?
├─ YES: Is status.replit.com reporting an incident?
│   ├─ YES → Platform issue. Wait for Replit. Communicate to users.
│   └─ NO → Your deployment issue. Continue below.
│
│   Can you access the Replit Workspace?
│   ├─ YES → Check deployment logs:
│   │   ├─ Build error → Fix code, redeploy
│   │   ├─ Runtime crash → Check logs, fix, redeploy
│   │   └─ Secret missing → Add to Secrets tab, redeploy
│   └─ NO → Network/browser issue. Try incognito window.
│
└─ App responds but with errors?
    ├─ 5xx errors → Check logs for crash/exception
    ├─ Slow responses → Check database, cold start, memory
    └─ Auth not working → Verify deployment domain, not dev URL

Remediation by Error Type

Deployment Crash (5xx / App Unreachable)

1. Open Repli

Replit Install & Auth

Overview

Set up a Replit App from scratch: configure .replit and replit.nix, manage Secrets (AES-256 encrypted environment variables), and integrate Replit Auth for zero-setup user authentication with Google, GitHub, Apple, X, and Email login.

Prerequisites

• Replit account (Free, Core, or Teams plan)
• Replit App created from template, GitHub import, or blank
• For Auth: deployed app on .replit.app or custom domain

Instructions

Step 1: Configure .replit File

# .replit — controls run behavior, deployment, and environment
entrypoint = "index.ts"
run = "npm start"

# Nix modules provide language runtimes
modules = ["nodejs-20:v8-20230920-bd784b9"]

[nix]
channel = "stable-24_05"

[env]
NODE_ENV = "development"
PORT = "3000"

[deployment]
run = ["sh", "-c", "npm start"]
deploymentTarget = "autoscale"
build = ["sh", "-c", "npm run build"]
ignorePorts = [3001]

[unitTest]
language = "nodejs"

[packager]
language = "nodejs"
  [packager.features]
  packageSearch = true
  guessImports = true

[gitHubImport]
requiredFiles = [".replit", "replit.nix"]

Step 2: Configure replit.nix

# replit.nix — system-level dependencies via Nix
{ pkgs }: {
  deps = [
    pkgs.nodejs-20_x
    pkgs.nodePackages.typescript-language-server
    pkgs.nodePackages.pnpm
    pkgs.postgresql
    pkgs.python311
    pkgs.python311Packages.pip
  ];
}

After editing replit.nix, reload the shell for changes to take effect.

Step 3: Configure Secrets

Secrets are encrypted with AES-256 at rest and TLS in transit. Two scopes:

• App-level: specific to one Replit App
• Account-level: shared across all your Apps

Via UI:
1. Click the lock icon (Secrets) in the left sidebar
2. Add key-value pairs:
   - DATABASE_URL = postgresql://...
   - API_KEY = sk-...
   - JWT_SECRET = your-jwt-secret

Via code — validate at startup:

// src/config.ts
function requireSecrets(keys: string[]): Record<string, string> {
  const missing = keys.filter(k => !process.env[k]);
  if (missing.length > 0) {
    console.error(`Missing secrets: ${missing.join(', ')}`);
    console.error('Add them in the Secrets tab (lock icon in sidebar)');
    process.exit(1);
  }
  return Object.fromEntries(keys.map(k => [k, process.env[k]!]));
}

const config = requireSecrets(['DATABASE_URL', 'JWT_SECRET']);

Secrets sync automatically between Workspace and Deployments. Replit'

Replit Local Dev Loop

Overview

Configure the Replit Workspace development cycle: run commands, hot reloading, port configuration, Webview preview, dev/production database separation, and Replit Agent for AI-assisted building.

Prerequisites

• Replit App with .replit configured
• Node.js or Python project initialized
• Familiarity with Replit Workspace UI

Instructions

Step 1: Configure Run Commands

# .replit — run determines what happens when you click "Run"

# Simple string command
run = "npm run dev"

# Array form (recommended for deployment)
# run = ["sh", "-c", "npm run dev"]

# Multiple services simultaneously
# run = "npm run api & npm run frontend & wait"

entrypoint = "index.ts"

Compiled languages need a compile step:

# TypeScript
compile = "npx tsc -b"
run = "node dist/index.js"

# Go
compile = "go build -o main ."
run = "./main"

Step 2: Hot Reload Setup

Node.js with tsx watch:

# .replit
run = "npx tsx watch src/index.ts"

{
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "test": "vitest",
    "test:watch": "vitest --watch"
  }
}

Python with Flask auto-reload:

run = "python main.py"

[env]
FLASK_DEBUG = "1"

# main.py — Flask auto-reloads in debug mode
if __name__ == '__main__':
    app.run(host='0.0.0.0', port=3000, debug=True)

Vite/Next.js dev server:

run = "npm run dev"

[env]
PORT = "3000"

Step 3: Port Configuration

Replit routes external traffic to your app's port. Your app must listen on 0.0.0.0:

// Correct — Replit can reach this
app.listen(3000, '0.0.0.0', () => console.log('Ready'));

// Wrong — unreachable from Webview
// app.listen(3000, '127.0.0.1', () => ...);

[deployment]
run = ["sh", "-c", "npm start"]
deploymentTarget = "autoscale"
# Ignore ports used by dev tools only
ignorePorts = [3001, 5555]

Use the Networking tool in the sidebar to view active port mappings.

Step 4: Dev vs Production Database

Replit provides separate development and production databases:

// Databases auto-switch based on context:
// - Workspace "Run&quo

Replit Migration Deep Dive

Current State

!cat .replit 2>/dev/null | head -10 || echo 'No .replit found'

!cat Procfile 2>/dev/null || echo 'No Procfile (not Heroku)'

!cat Dockerfile 2>/dev/null | head -10 || echo 'No Dockerfile'

!cat railway.json 2>/dev/null || echo 'No railway.json'

Overview

Comprehensive guide for migrating existing applications to Replit from Heroku, Railway, Vercel, Render, or local development. Covers converting configuration files, migrating databases, adapting to Replit's Nix-based environment, and setting up Replit-native features.

Prerequisites

• Source application with working deployment
• Access to current database for export
• Git repository with application code
• Replit Core or Teams plan

Migration Paths

Instructions

Step 1: Import from GitHub

1. Go to replit.com > Create Repl > Import from GitHub
2. Paste your repository URL
3. Replit auto-detects language and creates default config
4. Review and adjust .replit and replit.nix

Step 2: Convert from Heroku

Procfile to .replit:

# Heroku Procfile
web: npm start
worker: node worker.js
release: node migrate.js

# Equivalent .replit
run = "npm start"
entrypoint = "index.js"

[deployment]
run = ["sh", "-c", "node migrate.js && npm start"]
build = ["sh", "-c", "npm ci --production"]
deploymentTarget = "autoscale"

[env]
NODE_ENV = "production"

Heroku addons to Replit services:

Workspace "Run" button → Development database
Deployed app (.replit.app) → Production database

Both use the same DATABASE_URL env var — Replit routes automatically.
No code changes needed between environments.

Repl 1: my-app-staging → Autoscale deployment → staging.replit.app
Repl 2: my-app-prod   → Reserved VM deployment → app.example.com

Each Repl has its own:
- Secrets (different API keys per environment)
- PostgreSQL database (separate data)
- Deployment configuration
- GitHub branch (staging → staging, main → production)

// src/config/environment.ts
type Environment = 'development' | 'staging' | 'production';

export function detectEnvironment(): Environment {
  // Replit deployment context
  if (process.env.REPL_DEPLOYMENT) {
    // Check if this is the staging Repl
    if (process.env.REPL_SLUG?.includes('staging')) return 'staging';
    return 'production';
  }

  // Workspace "Run" context
  if (process.env.REPL_SLUG) return 'development';

  // Fallback to NODE_ENV
  const env = process.env.NODE_ENV || 'development';
  if (env === 'production') return 'production';
  if (env === 'staging') return 'staging';
  return 'development';
}

export const ENV = detectEnvironment();
export const IS_PROD = ENV === 'production';

// src/config/index.ts
import { ENV, IS_PROD } from './environment';

const configs = {
  development: {
    logLevel: 'debug',
    corsOrigins: ['*'],
    rateLimit: { windowMs: 60000, max: 1000 },
    cache: { ttlMs: 5000 },
    features: { debugEndpoints: true },
  },
  staging: {
    logLevel: 'info',
    corsOrigins: ['https://staging.example.com'],
    rateLimit: { windowMs: 60000, max: 200 },
    cache: { ttlMs: 30000 },
    features: { debugEndpoin

// src/routes/health.ts — comprehensive health check
import { Router } from 'express';
import { pool } from '../services/postgres';

const router = Router();
const startTime = Date.now();

router.get('/health', async (req, res) => {
  const checks: Record<string, any> = {
    status: 'ok',
    uptime: process.uptime(),
    bootTime: ((Date.now() - startTime) / 1000).toFixed(1) + 's ago',
    timestamp: new Date().toISOString(),
    repl: process.env.REPL_SLUG,
    region: process.env.REPLIT_DEPLOYMENT_REGION,
    env: process.env.NODE_ENV,
  };

  // Database check
  if (process.env.DATABASE_URL) {
    const dbStart = Date.now();
    try {
      await pool.query('SELECT 1');
      checks.database = {
        status: 'connected',
        latencyMs: Date.now() - dbStart,
        pool: { total: pool.totalCount, idle: pool.idleCount },
      };
    } catch (err: any) {
      checks.database = { status: 'disconnected', error: err.message };
      checks.status = 'degraded';
    }
  }

  // Memory metrics
  const mem = process.memoryUsage();
  checks.memory = {
    heapMB: Math.round(mem.heapUsed / 1024 / 1024),
    totalMB: Math.round(mem.heapTotal / 1024 / 1024),
    rssMB: Math.round(mem.rss / 1024 / 1024),
    percent: ((mem.heapUsed / mem.heapTotal) * 100).toFixed(1),
  };

  // Node.js info
  checks.runtime = {
    node: process.version,
    platform: process.platform,
    pid: process.pid,
  };

  res.status(checks.status === 'ok' ? 200 : 503).json(checks);
});

// Lightweight ping for uptime monitors
router.get('/ping', (req, res) => res.send('pong'));

export default router;

// src/utils/logger.ts — structured JSON logging
const IS_PROD = process.env.NODE_ENV === 'production';

type LogLevel = 'debug' | 'info' | 'warn' | 'error';

function log(level: LogLevel, message: string, data?: Record<string, any>) {
  if (level === 'debug' && IS_PROD) return;

  const entry = {
    timestamp: new Date().toISOString(),
    level,
    message,
    repl: process.env.REPL_SLUG,
    ...data,
  };

  // JSON format for machine parsing, human-readable in dev
  if (IS_PROD) {
    console[level === '

// 1. Lazy-load heavy modules — only import when needed
// BAD: imports everything at startup
import { heavyAnalytics } from './analytics'; // 500ms
import { imageProcessor } from './images';     // 300ms

// GOOD: import on demand
app.get('/api/analyze', async (req, res) => {
  const { heavyAnalytics } = await import('./analytics');
  res.json(await heavyAnalytics.process(req.query));
});

// 2. Defer non-critical initialization
let dbPool: Pool | null = null;

function getDB(): Pool {
  if (!dbPool) {
    dbPool = new Pool({
      connectionString: process.env.DATABASE_URL,
      ssl: { rejectUnauthorized: false },
      max: 5,  // Keep pool small for faster init
    });
  }
  return dbPool;
}

// 3. Start server immediately, initialize after
const app = express();
const PORT = parseInt(process.env.PORT || '3000');
app.listen(PORT, '0.0.0.0', () => {
  console.log(`Server ready in ${process.uptime().toFixed(1)}s`);
  // Warm up in background after server is accepting requests
  warmup().catch(console.error);
});

async function warmup() {
  await getDB().query('SELECT 1');  // Pre-connect
}

# replit.nix — only include what you actually need

# BAD: kitchen-sink approach
{ pkgs }: {
  deps = [
    pkgs.nodejs-20_x
    pkgs.python311
    pkgs.go
    pkgs.rustc
    pkgs.cargo
    pkgs.postgresql
    pkgs.redis
    pkgs.imagemagick
  ];
}

# GOOD: minimal deps for a Node.js app
{ pkgs }: {
  deps = [
    pkgs.nodejs-20_x
    pkgs.nodePackages.typescript-language-server
  ];
  # Only add postgresql if you need psql CLI:
  # pkgs.postgresql
}

# .replit — pin Nix channel for cache hits
[nix]
channel = "stable-24_05"
# Changing channel invalidates all Nix caches
# Only upgrade when needed

# .replit — fast production builds
[deployment]
build = ["sh", "-c", "npm ci --production && npm run build"]
run = ["sh", "-c", "node dist/index.js"]

// package.json — optimize

# CRITICAL POLICY: Never hardcode secrets in source files

# BAD — visible to anyone viewing your Repl
API_KEY = "sk-live-abc123"
DB_PASSWORD = "p@ssw0rd"

# GOOD — use Replit Secrets (AES-256 encrypted)
import os

API_KEY = os.environ.get("API_KEY")
if not API_KEY:
    raise RuntimeError("API_KEY not set. Add it in the Secrets tab (lock icon).")

# Startup validation — fail fast if secrets missing
REQUIRED_SECRETS = ["API_KEY", "DATABASE_URL", "JWT_SECRET"]
missing = [s for s in REQUIRED_SECRETS if not os.environ.get(s)]
if missing:
    raise RuntimeError(f"Missing required secrets: {missing}")

// Pre-deploy check script: scripts/check-secrets.ts
import { readFileSync, readdirSync, statSync } from 'fs';
import { join } from 'path';

const SECRET_PATTERNS = [
  /sk[-_](?:live|test)[-_]\w{20,}/,     // API keys
  /(?:password|passwd|pwd)\s*[:=]\s*['"][^'"]+['"]/i,
  /(?:secret|token)\s*[:=]\s*['"][^'"]{10,}['"]/i,
  /-----BEGIN (?:RSA |EC )?PRIVATE KEY-----/,
  /eyJ[A-Za-z0-9-_]+\.eyJ[A-Za-z0-9-_]+/,  // JWT tokens
];

function scanFile(filepath: string): string[] {
  const content = readFileSync(filepath, 'utf-8');
  const issues: string[] = [];

  SECRET_PATTERNS.forEach((pattern, i) => {
    if (pattern.test(content)) {
      issues.push(`${filepath}: potential secret found (pattern ${i})`);
    }
  });

  return issues;
}

function scanDirectory(dir: string): string[] {
  const issues: string[] = [];
  const entries = readdirSync(dir);

  for (const entry of entries) {
    if (['.git', 'node_modules', '.cache', 'dist'].includes(entry)) continue;
    const path = join(dir, entry);
    if (statSync(path).isDirectory()) {
      issues.push(...scanDirectory(path));
    } else if (/\.(ts|js|py|json|env|yaml|yml|toml)$/.test(entry)) {
      issues.push(...scanFile(path));
    }
  }

  return issues;
}

const issues = scanDirectory('.');
if (issues.length > 0) {
  console.error('SECRET SCAN FAILED:');
  issues.forEach(i => console.error(`  ${i}`));
  process.exit(1);

[deployment]
run = ["sh", "-c", "npm start"]
build = ["sh", "-c", "npm ci --production && npm run build"]
deploymentTarget = "autoscale"  # or "cloudrun" for Reserved VM

const REQUIRED = ['DATABASE_URL', 'JWT_SECRET'];
const missing = REQUIRED.filter(k => !process.env[k]);
if (missing.length) {
  console.error(`FATAL: Missing secrets: ${missing.join(', ')}`);
  process.exit(1);
}

app.get('/health', async (req, res) => {
  const checks = {
    db: false,
    uptime: process.uptime(),
    memory: Math.round(process.memoryUsage().heapUsed / 1024 / 1024),
  };

  try {
    await pool.query('SELECT 1');
    checks.db = true;
  } catch {}

  const status = checks.db ? 200 : 503;
  res.status(status).json({ status: status === 200 ? 'healthy' : 'degraded', ...checks });
});

// Never expose stack traces in production
app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
  console.error('Unhandled error:', err.message);
  res.status(500).json({
    error: process.env.NODE_ENV === 'production'
      ? 'Internal server error'
      : err.message,
  });
});

process.on(

// Check how close you are to KV limits
import Database from '@replit/database';

async function checkKVUsage() {
  const db = new Database();
  const keys = await db.list();
  let totalSize = 0;

  for (const key of keys) {
    const value = await db.get(key);
    const valueSize = JSON.stringify(value).length;
    totalSize += key.length + valueSize;
  }

  const limitMiB = 50;
  const usedMiB = totalSize / (1024 * 1024);
  const percentUsed = (usedMiB / limitMiB * 100).toFixed(1);

  console.log(`KV Usage: ${usedMiB.toFixed(2)} MiB / ${limitMiB} MiB (${percentUsed}%)`);
  console.log(`Keys: ${keys.length} / 5,000`);

  if (parseFloat(percentUsed) > 80) {
    console.warn('WARNING: KV database above 80%. Consider migrating large values to Object Storage.');
  }
}

// src/middleware/rate-limit.t

                    ┌──────────────────────────┐
                    │    Client (Browser)       │
                    └──────────┬───────────────┘
                               │ HTTPS
                    ┌──────────▼───────────────┐
                    │  Replit Proxy (TLS, Auth) │
                    │  Injects X-Replit-User-*  │
                    └──────────┬───────────────┘
                               │
┌──────────────────────────────▼──────────────────────────────┐
│                 Replit Deployment                            │
│                                                              │
│  ┌─────────────┐  ┌──────────────┐  ┌───────────────────┐  │
│  │ .replit      │  │ replit.nix   │  │ Secrets (AES-256) │  │
│  │ (run/build)  │  │ (Nix deps)   │  │ (env vars)        │  │
│  └─────────────┘  └──────────────┘  └───────────────────┘  │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐   │
│  │              Express / Flask Server                   │   │
│  │  Routes │ Auth Middleware │ Error Handler │ Health    │   │
│  └────────┬───────────────────────────────────┬─────────┘   │
│           │                                   │              │
│  ┌────────▼──────────┐  ┌───────────────────▼────────────┐ │
│  │  PostgreSQL       │  │  Replit KV Database            │ │
│  │  (DATABASE_URL)   │  │  (REPLIT_DB_URL)               │ │
│  │  Dev + Prod DBs   │  │  50 MiB, 5K keys              │ │
│  └───────────────────┘  └────────────────────────────────┘ │
│                                                              │
│  ┌─────────────────────────────────────────────────────────┐│
│  │  Object Storage (App Storage)                           ││
│  │  File uploads, backups, large data                      ││
│  │  @replit/object-storage SDK                             ││
│  └─────────────────────────────────────────────────────────┘│
│                                                              │
│  Deployment: Autoscale │ Reserved VM │ Static               │
└──────────────────────────────────────────────────────────────┘

my-replit-app/
├── .replit                    # Run + deployment configuration
├── replit.nix                 # System-level Nix dependencies
├── package.json               # npm dependencies + scripts
├── tsconfig.json              # TypeScript config
├── src/
│   ├── index.ts               # Entry point — Express setup
│   ├── config.ts              # Secrets validation + env config
│   ├── routes/
│   │   ├── 

Container starts → App boots → Handles requests → [Sleep or Restart]
                                                         │
                    ┌────────────────────────────────────┘
                    │
            ┌───────┴──────┐
            │ Sleep trigger │  Autoscale: no traffic for ~5 min
            │ Restart trigger│  Deploy, config change, or crash
            └───────┬──────┘
                    │
        State lost: filesystem, in-memory data, caches
        State kept: PostgreSQL, KV Database, Object Storage, Secrets

// Handle cold starts — prioritize accepting requests over initialization
import express from 'express';

const app = express();
let ready = false;

// Accept requests immediately
app.listen(parseInt(process.env.PORT || '3000'), '0.0.0.0', () => {
  console.log(`Server started in ${process.uptime().toFixed(1)}s`);
  // Initialize in background
  initialize().catch(console.error);
});

// Health endpoint reflects readiness
app.get('/health', (req, res) => {
  res.status(ready ? 200 : 503).json({
    status: ready ? 'ready' : 'initializing',
    uptime: process.uptime(),
  });
});

async function initialize() {
  const start = Date.now();
  // Pre-connect database
  await pool.query('SELECT 1');
  // Warm caches
  await warmCache();
  ready = true;
  console.log(`Initialization complete in ${Date.now() - start}ms`);
}

// Graceful shutdown handler
let shutdownInProgress = false;

async function shutdown(signal: string) {
  if (shutdownInProgress) return;
  shutdownInProgress = true;

  console.log(`${signal} received. Shutting down gracefully...`);

  // 1. Stop accepting new requests
  server.close();

  // 2. Finish in-flight requests (give them 10 seconds)
  await new Promise(resolve => setTimeout(resolve, 10000));

  // 3. Save critical state
  try {
    await saveAppState();
  } catch (err: any) {
    console.error('Failed to save state:', err.message);
  }

  // 4. Close database connections
  await pool.end();

  // 5. Close KV database
  // @replit/database: call close() to terminate cleanly
  // replit.db (Python): call repl

// src/db/kv.ts — Replit Key-Value Database wrapper
import Database from '@replit/database';

let instance: Database | null = null;

export function getKV(): Database {
  if (!instance) {
    instance = new Database();
  }
  return instance;
}

// Type-safe KV operations
export async function kvGet<T>(key: string): Promise<T | null> {
  const value = await getKV().get(key);
  return value as T | null;
}

export async function kvSet<T>(key: string, value: T): Promise<void> {
  await getKV().set(key, value);
}

export async function kvList(prefix = ''): Promise<string[]> {
  return getKV().list(prefix);
}

export async function kvDelete(key: string): Promise<void> {
  await getKV().delete(key);
}

// Limits: 50 MiB total, 5,000 keys, 1 KB/key, 5 MiB/value

// src/storage/objects.ts — Replit App Storage (Object Storage)
import { Client } from '@replit/object-storage';

let storage: Client | null = null;

export function getStorage(): Client {
  if (!storage) {
    storage = new Client();
  }
  return storage;
}

// Upload with error handling
export async function uploadText(path: string, content: string): Promise<void> {
  try {
    await getStorage().uploadFromText(path, content);
  } catch (err: any) {
    if (err.name === 'BucketNotFoundError') {
      throw new Error('Object Storage bucket not provisioned. Create one in the Object Storage pane.');
    }
    if (err.name === 'TooManyRequestsError') {
      throw new Error('Object Storage rate limited. Retry after backoff.');
    }
    throw err;
  }
}

// Download with fallback
export async function downloadText(path: string, fallback = ''): Promise<string> {
  try {
    const { value } = await getStorage().downloadAsText(path);
    return value ?? fallback;
  } catch {
    return fallback;
  }
}

// List with prefix filtering
export async function listObjects(prefix: string): Promise<string[]> {
  const objects = await getStorage().list({ prefix });
  return objects.map(obj => obj.name);
}

// src/d

App-level secrets: Specific to one Repl (lock icon in sidebar)
Account-level secrets: Apply across all your Repls (Account Settings > Secrets)

// Validate all required secrets at startup — fail fast
const REQUIRED = ['DATABASE_URL', 'JWT_SECRET', 'API_KEY'];
const missing = REQUIRED.filter(k => !process.env[k]);
if (missing.length) {
  console.error(`Missing secrets: ${missing.join(', ')}`);
  console.error('Add them in the Secrets tab (lock icon in sidebar)');
  process.exit(1);
}

# CRITICAL: Never hardcode secrets in source files
# BAD — visible to anyone who views your Repl
API_KEY = "sk-live-abc123"  # exposed!

# GOOD — use Replit Secrets
import os
API_KEY = os.environ.get("API_KEY")

# .gitignore (also applies if you connect Repl to GitHub)
.env
.env.local
*.pem
*.key

// Verify a request came from a specific Repl
import { verify } from '@replit/repl-auth';

function verifyReplIdentity(identityToken: string): boolean {
  try {
    // REPL_PUBKEYS contains the ED25519 public key (base64-encoded)
    const pubkeys = JSON.parse(process.env.REPL_PUBKEYS || '{}');
    const payload = verify(identityToken, pubkeys);
    // payload contains: replId, user, slug, aud
    return !!payload;
  } catch {
    return false;
  }
}

// Use in middleware for Repl-to-Repl calls
app.post('/internal/api', (req, res) => {
  const identity = req.headers['x-repl-identity'] as string;
  if (!verifyReplIdentity(identity)) {
    return res.status(403).json({ error: 'Invalid Repl identity' });
  }
  // Process trusted request
}

# .replit — before
[nix]
channel = "stable-23_05"

# .replit — after (2024-2025 stable)
[nix]
channel = "stable-24_05"

node --version     # Should show newer version
python3 --version  # Should show newer version

# replit.nix — update runtime packages

# Before (Node 18)
{ pkgs }: {
  deps = [
    pkgs.nodejs-18_x
    pkgs.nodePackages.typescript
  ];
}

# After (Node 20)
{ pkgs }: {
  deps = [
    pkgs.nodejs-20_x
    pkgs.nodePackages.typescript-language-server
    pkgs.nodePackages.pnpm
  ];
}

# .replit — update modules to match
modules = ["nodejs-20:v8-20230920-bd784b9"]

node --version         # v20.x.x
npm --version          # 10.x.x
npm test               # Run tests to catch breaking changes

// scripts/migrate-kv-to-postgres.ts
import Database from '@replit/database';
import { Pool } from 'pg';

const kv = new Database();
const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  ssl: { rejectUnauthorized: false },
});

async function migrate() {
  // Create table
  await pool.query(`
    CREATE TABLE IF NOT EXISTS kv_data (
      key TEXT PRIMARY KEY,
      value JSONB NOT NULL,
      migrated_at TIMESTAMPTZ DEFAULT NOW()
    )
  `);

  // Read all KV entries
  const keys = await kv.list();
  console.log(`Migrating ${keys.length} keys...`);

  let migrated = 0;
  let errors = 0;

  for (const key of keys) {
    try {
      const value = await kv.get(key);
      await pool.query(
        'INSERT INTO kv_data (key, value) VALUES ($1, $2) ON CONFLICT (key) DO UPDATE SET value = $2',
        [key, JSON.stringify(value)]
      );
      migrated+

// src/deploy-monitor.ts — Track deployment health
import express from 'express';

const app = express();
app.use(express.json());

// Health endpoint that deployment monitoring can ping
app.get('/health', async (req, res) => {
  res.json({
    status: 'healthy',
    environment: process.env.REPL_SLUG,
    region: process.env.REPLIT_DEPLOYMENT_REGION,
    deployedAt: process.env.REPLIT_DEPLOYMENT_TIMESTAMP || 'unknown',
    uptime: process.uptime(),
  });
});

// Post-deploy smoke test endpoint
app.get('/api/readiness', async (req, res) => {
  const checks = {
    database: await checkDB(),
    storage: await checkStorage(),
    secrets: checkSecrets(),
  };

  const allHealthy = Object.values(checks).every(Boolean);
  res.status(allHealthy ? 200 : 503).json({ ready: allHealthy, checks });
});

async function checkDB(): Promise<boolean> {
  try {
    const { Pool } = await import('pg');
    const pool = new Pool({ connectionString: process.env.DATABASE_URL });
    await pool.query('SELECT 1');
    await pool.end();
    return true;
  } catch { return false; }
}

async function checkStorage(): Promise<boolean> {
  try {
    const { Client } = await import('@replit/object-storage');
    const storage = new Client();
    await storage.list({ maxResults: 1 });
    return true;
  } catch { return false; }
}

function checkSecrets(): boolean {
  const required = ['DATABASE_URL', 'JWT_SECRET'];
  return required.every(k => !!process.env[k]);
}

// src/webhooks.ts — Receive webhooks from GitHub, Stripe, etc.
import express from 'express';
import crypto from 'crypto';

const router = express.Router();

// Webhook signature verification
function verifySignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expected}`)
  );
}

// GitHub webhook receiver
router.post('/webho