replit-common-errors

name	replit-common-errors
description	Diagnose and fix the top Replit errors: container sleep, port binding, Nix failures, DB limits. Use when encountering Replit errors, debugging failed deployments, or troubleshooting workspace and hosting issues. Trigger with phrases like "replit error", "fix replit", "replit not working", "debug replit", "replit broken", "replit deploy failed".
allowed-tools	Read, Grep, Bash(curl:*)
version	1.12.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","replit","debugging","errors"]
compatibility	Designed for Claude Code

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]
 =