From replit-pack
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".
How this skill is triggered — by the user, by Claude, or both
Slash command
/replit-pack:replit-common-errorsThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Quick reference for the 10 most common Replit errors with real solutions. Covers container lifecycle, Nix configuration, database, deployment, and networking issues.
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.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub flight505/skill-forge --plugin replit-pack