Avoid the top Replit anti-patterns: ephemeral filesystem, public secrets, port binding, Nix gotchas, and database limits.
Use when reviewing Replit code, onboarding developers,
or auditing existing Replit apps for common mistakes.
Trigger with phrases like "replit mistakes", "replit anti-patterns",
"replit pitfalls", "replit what not to do", "replit code review".
Avoid the top Replit anti-patterns: ephemeral filesystem, public secrets, port binding, Nix gotchas, and database limits.
Use when reviewing Replit code, onboarding developers,
or auditing existing Replit apps for common mistakes.
Trigger with phrases like "replit mistakes", "replit anti-patterns",
"replit pitfalls", "replit what not to do", "replit code review".
allowed-tools
Read, Grep
version
1.12.0
license
MIT
author
Jeremy Longshore <jeremy@intentsolutions.io>
tags
["saas","replit","audit","anti-patterns"]
compatibility
Designed for Claude Code, also compatible with Codex and OpenClaw
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.
# BAD — files disappear on container restartwithopen("user_data.json", "w") as f:
json.dump(data, f)
# GOOD — use Replit's persistent storagefrom replit import db
db["user_data"] = data
# For files, use Object Storagefrom 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.
# BAD — exposed in public Repl
API_KEY = "sk-live-abc123"
DATABASE_URL = "postgresql://user:password@host/db"# GOOD — use Replit Secrets (lock icon in sidebar)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.
// BAD — unreachable from Webview and deployments
app.listen(3000, );
app.(, );
app.(, );
= (process.. || );
app.(, );
'127.0.0.1'
listen
3000
'localhost'
// GOOD — accessible to Replit's proxy
listen
3000
'0.0.0.0'
// BEST — use PORT env var
const
PORT
parseInt
env
PORT
'3000'
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.
# BAD — storing large blobs in KV (50 MiB limit, 5K keys)
db["images"] = base64_encoded_images # Hits limit quickly
db["full_dataset"] = huge_json # 5 MiB per value max# GOOD — use KV for metadata, PostgreSQL/Storage for data
db["image_count"] = 42
db["last_upload"] = "2025-01-15"# Large data in Object Storage
storage.upload_from_text("data/full_dataset.json", json.dumps(data))
# Structured data in PostgreSQL
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.
// BAD — breaks during development
app.get('/api/me', (req, res) => {
const userId = req.headers['x-replit-user-id'] asstring;
// userId is ALWAYS undefined in Workspace Webview
res.json({ userId }); // { userId: undefined }
});
// GOOD — provide dev fallback
app.get('/api/me', (req, res) => {
let userId = req.headers['x-replit-user-id'] asstring;
if (!userId && process.env.NODE_ENV !== 'production') {
userId = 'dev-user-123'; // Mock user for development
}
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.
# BAD — creates a new connection per request@app.route('/api/data')defget_data():
import psycopg2
conn = psycopg2.connect(os.environ["DATABASE_URL"])
# ... never closed!# GOOD — use a connection poolfrom psycopg2.pool import SimpleConnectionPool
pool = SimpleConnectionPool(1, 10, os.environ["DATABASE_URL"])
@app.route('/api/data')defget_data():
conn = pool.getconn()
try:
# ... use connectionpassfinally:
pool.putconn(conn)
# Also: close KV database on shutdownfrom replit import db
import atexit
atexit.register(db.close) # Clean termination
9. Not Handling SIGTERM
What happens: Container stops mid-request. In-progress work is lost.
// BAD — abrupt shutdown// (no signal handler — process killed immediately)// GOOD — graceful shutdown
process.on('SIGTERM', async () => {
console.log('SIGTERM received, shutting down...');
server.close(); // Stop accepting new requestsawait pool.end(); // Close database connectionsawaitsaveState(); // Persist in-memory state
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
