replit-common-errors

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 REPLIT_DB_URL instead

---

5. Replit DB Write Failure (50MB Limit)

Error: Max storage size exceeded

Cause: Key-Value Database has a 50 MiB total limit (keys + values). Solution:

# Check current usage
from replit import db
total_keys = len(list(db.keys()))
print(f"Keys: {total_keys} / 5000")

# Migrate large data to Object Storage or PostgreSQL
from replit.object_storage import Client
storage = Client()
storage.upload_from_text('large-data.json', json.dumps(big_data))
del db['large_key']  # Free up KV space

---

6. Object Storage Bucket Not Found

Error: BucketNotFoundError: No bucket found

Cause: Object Storage bucket not provisioned for this Repl. Solution:

1. Open the Object Storage pane in the sidebar
2. Create a new bucket (auto-names based on Repl)
3. Then use new Client() with no arguments — it auto-discovers

---

7. Auth Headers Empty

req.headers['x-replit-user-id'] === undefined

Cause: Replit Auth only works on deployed apps (.replit.app or custom domain), not in the Workspace Webview during development. Solution:

// Mock auth in development
function getUser(req: Request) {
  const userId = req.headers['x-replit-user-id'] as string;
  if (!userId && process.env.NODE_ENV !== 'production') {
    return { id: 'dev-user', name: 'Developer', image: '' };
  }
  if (!userId) return null;
  return {
    id: userId,
    name: req.headers['x-replit-user-name'] as string,
    image: req.headers['x-replit-user-profile-image'] as string,
  };
}

---

8. Module Not Found After Nix Change

Error: Cannot find module '@replit/database'

Cause: npm packages need separate install from Nix system packages. Solution:

# Nix = system packages (Python runtime, PostgreSQL, etc.)
# npm/pip = language packages (express, flask, etc.)

# Both are needed:
# In replit.nix: pkgs.nodejs-20_x
# In shell: npm install @replit/database @replit/object-storage

# For Python:
# In replit.nix: pkgs.python311
# In shell: pip install replit flask

---

9. Deployment Build Timeout

Error: Build exceeded time limit

Cause: Heavy dependencies or slow build step. Solution:

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

# Tips:
# - Use npm ci instead of npm install
# - Use --production to skip devDependencies
# - Use TypeScript incremental builds: tsc --incremental
# - Remove unused packages from package.json

---

10. Secrets Not Available in Deployment

Error: API_KEY is undefined in production

Cause: Secrets added in Workspace may not have synced (legacy behavior). Solution:

• As of 2025, deployment secrets sync automatically with Workspace secrets
• Verify in Deployments > Settings > Environment Variables
• For Account-level secrets: Settings > Secrets (applies to all Repls)
• Restart the deployment after adding secrets

Quick Diagnostics

# Check Replit status
curl -s https://status.replit.com/api/v2/summary.json | jq '.status.description'

# Check built-in env vars
echo "REPL_SLUG=$REPL_SLUG"
echo "REPL_OWNER=$REPL_OWNER"
echo "REPLIT_DB_URL=${REPLIT_DB_URL:+SET}"
echo "DATABASE_URL=${DATABASE_URL:+SET}"

# Check installed packages
npm list --depth=0 2>/dev/null
pip list 2>/dev/null | head -20

Resources

• Replit Status Page
• Replit Docs
• Nix on Replit
• Replit Secrets

Next Steps

For comprehensive debugging, see replit-debug-bundle.