Apply Replit advanced debugging techniques for hard-to-diagnose issues.
Use when standard troubleshooting fails, investigating complex race conditions,
or preparing evidence bundles for Replit support escalation.
Trigger with phrases like "replit hard bug", "replit mystery error",
"replit impossible to debug", "difficult replit issue", "replit deep debug".
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 symlinks
rm -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 time
const startTime = Date.now();
console.log(`Starting at ${new Date().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.
const SAMPLE_INTERVAL = 30000; // 30 seconds
const samples: 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 growth
if (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 window
console.warn(`MEMORY LEAK SUSPECTED: +${growth.toFixed(0)}MB over ${samples.length * 30}s`);
console.warn(`Current: ${heapMB}MB, Samples: ${samples.length}`);
}
}
// Emergency: approaching container limit
if (heapMB > 450) { // Assuming 512MB container
console.error(`CRITICAL: Heap at ${heapMB}MB — approaching container limit`);
// Force garbage collection if available
global.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
