Debug hard Replit issues: container lifecycle, Nix build failures, deployment crashes, and memory leaks.
Use when standard troubleshooting fails, investigating intermittent failures,
or diagnosing complex Replit platform behavior.
Trigger with phrases like "replit hard bug", "replit mystery error",
"replit impossible to debug", "replit intermittent", "replit deep debug".
Instrucciones de origen · Vista previa de solo lectura
name
replit-advanced-troubleshooting
description
Debug hard Replit issues: container lifecycle, Nix build failures, deployment crashes, and memory leaks.
Use when standard troubleshooting fails, investigating intermittent failures,
or diagnosing complex Replit platform behavior.
Trigger with phrases like "replit hard bug", "replit mystery error",
"replit impossible to debug", "replit intermittent", "replit deep debug".
Designed for Claude Code, also compatible with Codex and OpenClaw
Replit Advanced Troubleshooting
Overview
Deep debugging techniques for complex Replit issues that resist standard troubleshooting. Covers container lifecycle problems, Nix environment failures, deployment crash loops, memory leaks in constrained containers, and isolating Replit platform vs application issues.
# When replit.nix changes cause build failures:# 1. Check what channel provides
nix-env -qaP 2>/dev/null | grep nodejs
# Shows available Node.js package names# 2. Common naming issues:# pkgs.nodejs → WRONG (ambiguous)# pkgs.nodejs-20_x → CORRECT# pkgs.python3 → WRONG (use pkgs.python311)# pkgs.python311 → CORRECT# 3. Verify current channel
grep channel .replit
# channel = "stable-24_05" is current# 4. After fixing replit.nix, reload shell:# Exit Shell tab, re-enter it# Or: exec $SHELL# 5. If packages won't install, try clearing Nix cache:# Remove generated Nix store symlinksrm -rf .config/nixpkgs 2>/dev/null
Step 3: Container Crash Loop Debugging
When deployment keeps crashing and restarting:
1. Check deployment logs (Deployment Settings > Logs)
Look for:
- "JavaScript heap out of memory" → increase VM size or fix leak
- "Cannot find module" → dependency not installed in build step
- "EACCES" → file permission issue
- "EADDRINUSE" → port conflict
2. Test locally first:
- Click "Run" in Workspace
- Check Console tab for errors
- Fix before deploying
3. Isolate the crash:
// Add to top of entry point — crash guard with logging
process.on('uncaughtException', (err) => {
console.error('UNCAUGHT EXCEPTION:', err.message);
console.error('Stack:', err.stack);
// Log the crash, then exit cleanly so Replit can restart
process.exit(1);
});
process.on('unhandledRejection', (reason: any) => {
console.error('UNHANDLED REJECTION:', reason?.message || reason);
console.error('Stack:', reason?.stack || 'no stack');
});
// Log startup timeconst startTime = Date.now();
console.log(`Starting at ${newDate().toISOString()}`);
// ... your app code ...
app.listen(PORT, '0.0.0.0', () => {
console.log(`Started in ${Date.now() - startTime}ms on port ${PORT}`);
});
Step 4: Memory Leak Detection
// Replit containers have fixed memory limits. Detect leaks early.constSAMPLE_INTERVAL = 30000; // 30 secondsconstsamples: number[] = [];
setInterval(() => {
const heapMB = Math.round(process.memoryUsage().heapUsed / 1024 / 1024);
samples.push(heapMB);
// Keep last 60 samples (30 minutes)if (samples.length > 60) samples.shift();
// Detect sustained growthif (samples.length >= 10) {
const first5 = samples.slice(0, 5).reduce((a, b) => a + b) / 5;
const last5 = samples.slice(-5).reduce((a, b) => a + b) / 5;
const growth = last5 - first5;
if (growth > 50) { // 50MB growth over observation windowconsole.warn(`MEMORY LEAK SUSPECTED: +${growth.toFixed(0)}MB over ${samples.length * 30}s`);
console.warn(`Current: ${heapMB}MB, Samples: ${samples.length}`);
}
}
// Emergency: approaching container limitif (heapMB > 450) { // Assuming 512MB containerconsole.error(`CRITICAL: Heap at ${heapMB}MB — approaching container limit`);
// Force garbage collection if availableglobal.gc?.();
}
}, SAMPLE_INTERVAL);
// Expose via health endpoint
app.get('/debug/memory', (req, res) => {
res.json({
current: process.memoryUsage(),
samples: samples.slice(-10),
trend: samples.length >= 2 ? samples[samples.length - 1] - samples[0] : 0,
});
});
Step 5: Deployment vs Workspace Differences
Common issues where code works in Workspace but fails in Deployment:
| Behavior | Workspace (Run) | Deployment |
|----------|-----------------|------------|
| Auth headers | NOT available | Available (X-Replit-User-*) |
| Database | Development DB | Production DB |
| Secrets | All visible | Auto-synced (2025+) |
| Filesystem | Persistent during session | Ephemeral (lost on restart) |
| Port | Any, mapped by Replit | Must use PORT env var |
| NODE_ENV | Usually unset | Set in .replit [env] |
Debugging steps:
1. Log process.env at startup to compare
2. Check if deployment has all required secrets
3. Verify build step produces correct output
4. Test with actual deployment URL, not Webview
When you need Replit support:
1. Collect: run replit-diagnose.sh
2. Document: steps to reproduce, expected vs actual
3. Screenshot: deployment logs, error messages
4. Submit: replit.com/support
Include:
- Repl URL (share link)
- Deployment URL
- Error messages (full text)
- When it started happening
- What changed before the issue
