Diagnose and fix Replit common errors and exceptions. Use when encountering Replit errors, debugging failed requests, or troubleshooting integration issues. Trigger with phrases like "replit error", "fix replit", "replit not working", "debug replit".
npxskills add jeremylongshore/claude-code-plugins-plus-skills--skill replit-common-errorsLoading…
Quick reference for the 10 most common Replit errors with real solutions. Covers container lifecycle, Nix configuration, database, deployment, and networking issues.
Error: Your Repl is sleeping. Run it to wake up.
Cause: Free/Hacker plan Repls sleep after ~5 minutes of inactivity. Solution:
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
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).
Error: Connection refused / ECONNREFUSED / DATABASE_URL is undefined
Cause: PostgreSQL not provisioned, or accessing outside Replit. Solution:
DATABASE_URL auto-populates in your environmentREPLIT_DB_URL insteadError: 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
Error: BucketNotFoundError: No bucket found
Cause: Object Storage bucket not provisioned for this Repl. Solution:
new Client() with no arguments — it auto-discoversreq.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,
};
}
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
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
Error: API_KEY is undefined in production
Cause: Secrets added in Workspace may not have synced (legacy behavior). Solution:
# 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
For comprehensive debugging, see replit-debug-bundle.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).