Replit Common Errors Skill

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:

Open the Database pane in the sidebar
Click "Create a database" if none exists
DATABASE_URL auto-populates in your environment
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:

Open the Object Storage pane in the sidebar
Create a new bucket (auto-names based on Repl)
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

Next Steps

For comprehensive debugging, see replit-debug-bundle.

Agent Skills: Replit Common Errors

Install this agent skill to your local

Skill Files