Replit Known Pitfalls
Overview
Real gotchas when building on Replit. Each pitfall includes what goes wrong, why, and the correct pattern. Based on common failures in Replit's ephemeral container model, Nix-based environment, and cloud hosting platform.
Pitfall Reference
1. Writing to Local Filesystem for Persistence
What happens: Data is lost when the container restarts, deploys, or sleeps.
with open("user_data.json", "w") as f:
json.dump(data, f)
from replit import db
db["user_data"] = data
from replit.object_storage import Client
storage = Client()
storage.upload_from_text("user_data.json", json.dumps(data))
Rule: Anything written to the filesystem is ephemeral. Use PostgreSQL, KV Database, or Object Storage for data that must survive restarts.
2. Hardcoding Secrets in Source Code
What happens: Secrets are visible to anyone who views your Repl (public by default on free plans). Replit's Secret Scanner catches some cases but not all.
API_KEY = "sk-live-abc123"
DATABASE_URL = "postgresql://user:password@host/db"
import os
API_KEY = os.environ["API_KEY"]
DATABASE_URL = os.environ["DATABASE_URL"]
3. Binding to localhost Instead of 0.0.0.0
What happens: App starts but Webview is blank. Replit's proxy can't reach the app.
app.listen(3000, '127.0.0.1');
app.listen(3000, 'localhost');
app.listen(3000, '0.0.0.0');
const PORT = parseInt(process.env.PORT || '3000');
app.listen(PORT, '0.0.0.0');
4. Ignoring Nix System Dependencies
What happens: Python packages with C extensions (Pillow, psycopg2, cryptography) fail to build with cryptic errors.
# BAD — missing system libraries
{ pkgs }: {
deps = [ pkgs.python311 ];
}
# GOOD — include system libraries for native packages
{ pkgs }: {
deps = [
pkgs.python311
pkgs.python311Packages.pip
pkgs.zlib # Required for Pillow
pkgs.libjpeg # Required for Pillow
pkgs.libffi # Required for cffi/cryptography
pkgs.openssl # Required for cryptography
pkgs.postgresql # Required for psycopg2
];
}
After editing replit.nix: Exit and re-enter the Shell tab to reload.
5. Using Replit KV Database for Large Data
What happens: Writes fail silently or throw errors after hitting the 50 MiB limit.
db["images"] = base64_encoded_images
db["full_dataset"] = huge_json
db["image_count"] = 42
db["last_upload"] = "2025-01-15"
storage.upload_from_text("data/full_dataset.json", json.dumps(data))
pool.query("INSERT INTO images (url, metadata) VALUES ($1, $2)", [url, meta])
KV Limits: 50 MiB total, 5,000 keys, 1 KB per key, 5 MiB per value.
6. Expecting Auth Headers in Development
What happens: X-Replit-User-Id is always undefined in Workspace Webview.
app.get('/api/me', (req, res) => {
const userId = req.headers['x-replit-user-id'] as string;
res.json({ userId });
});
app.get('/api/me', (req, res) => {
let userId = req.headers['x-replit-user-id'] as string;
if (!userId && process.env.NODE_ENV !== 'production') {
userId = 'dev-user-123';
}
if (!userId) return res.status(401).json({ error: 'Login required' });
res.json({ userId });
});
Auth only works on: deployed .replit.app URLs, .replit.dev preview URLs, and custom domains.
7. Using "Always On" Instead of Deployments
What happens: Legacy "Always On" feature is more expensive and less reliable than modern Deployments.
BAD (legacy):
Settings > Always On > Enable
- Keeps Repl running but uses more resources
- No build step, no rollbacks, no scaling
GOOD (modern):
Deploy button > Autoscale or Reserved VM
- Built-in rollbacks
- Separate dev/prod databases
- Auto-scaling (Autoscale)
- Build step for optimization
- Custom domains with auto-SSL
8. Forgetting to Close Database Connections
What happens: Connection pool exhaustion. New requests fail with timeout errors.
@app.route('/api/data')
def get_data():
import psycopg2
conn = psycopg2.connect(os.environ["DATABASE_URL"])
from psycopg2.pool import SimpleConnectionPool
pool = SimpleConnectionPool(1, 10, os.environ["DATABASE_URL"])
@app.route('/api/data')
def get_data():
conn = pool.getconn()
try:
pass
finally:
pool.putconn(conn)
from replit import db
import atexit
atexit.register(db.close)
9. Not Handling SIGTERM
What happens: Container stops mid-request. In-progress work is lost.
process.on('SIGTERM', async () => {
console.log('SIGTERM received, shutting down...');
server.close();
await pool.end();
await saveState();
process.exit(0);
});
10. Mixing npm and System Packages
What happens: Confusion between Nix system packages and npm/pip language packages.
Nix (replit.nix) = system packages:
- Node.js runtime, Python runtime
- System libraries (zlib, openssl, libjpeg)
- CLI tools (postgresql client, git)
npm/pip = language packages:
- express, flask, react
- @replit/database, @replit/object-storage
- pg, psycopg2
Both are needed:
1. replit.nix: pkgs.nodejs-20_x (provides Node.js)
2. Shell: npm install express (provides Express)
Common mistake:
Expecting "npm install" to provide system libraries
→ Need pkgs.openssl in replit.nix for crypto packages
Quick Audit Script
#!/bin/bash
echo "=== Replit Pitfall Audit ==="
echo -n "Secrets in code: "
grep -rn "sk[-_]\(live\|test\)" --include="*.py" --include="*.ts" --include="*.js" . 2>/dev/null | grep -v node_modules | wc -l
echo -n "Localhost binding: "
grep -rn "localhost\|127\.0\.0\.1" --include="*.py" --include="*.ts" --include="*.js" . 2>/dev/null | grep -v node_modules | grep -c "listen\|bind"
echo -n "Filesystem writes: "
grep -rn "writeFileSync\|open.*['\"]w['\"]" --include="*.py" --include="*.ts" --include="*.js" . 2>/dev/null | grep -v node_modules | grep -v ".replit\|replit.nix" | wc -l
echo -n "replit.nix: "
[ -f replit.nix ] && echo "exists" || echo "MISSING"
echo -n "SIGTERM handler: "
grep -rn "SIGTERM" --include="*.py" --include="*.ts" --include="*.js" . 2>/dev/null | grep -v node_modules | wc -l
Resources
Next Steps
For production readiness, see replit-prod-checklist.
