First: is it Replit, or is it you?
Before you spend an hour debugging your app, spend two minutes ruling out the alternative. Open replit.health (this site) and status.replit.com side by side. Green here and green there means the issue is almost certainly local: try a different network, disable browser extensions, open the workspace in an incognito profile, or test from a phone hotspot. Yellow or red on either page means Replit itself is degraded — you are not going to fix it from your keyboard, and the right move is to wait for the incident to resolve rather than making destructive changes that could compound the problem.
IDE is slow or unresponsive
A sluggish workspace usually falls into one of three buckets. First, the Repl is too big — too many files, too many open tabs, or a build process hogging CPU in the background. Close other tabs, kill any watch processes you do not need, and consider splitting the project into multiple Repls. Second, your local browser is the bottleneck: a hundred tabs plus a memory-hungry extension plus a Zoom call will strangle the workspace regardless of what Replit is doing. Third, Replit's edge infrastructure is degraded — check the status pages and, if it is confirmed, walk away and come back in ten minutes.
Agent runs stalling mid-turn
Agent failures almost always trace back to upstream model providers. Anthropic and OpenAI both have their own status pages and outages; when either has a rough day, Replit Agent inherits the pain because it routes to them. The signature is an Agent run that starts, thinks for a while, and then either hangs indefinitely or errors with a provider-side message. Cancel the run, wait a minute, and retry with a shorter prompt or a more constrained task. If the same tool call keeps hanging, temporarily disable that tool for the run — most stalls are on a single tool, not the model itself.
Build stuck 'Building' forever
Stuck builds almost never recover on their own. Cancel and redeploy after ten minutes of no progress. If the second attempt also hangs, read the build log carefully — the last live line is usually the clue. Common culprits: a package that requires a native binary Replit's Nix environment does not have, a post-install script that tries to reach the network from inside the build sandbox, or a build step that expects a specific version of Python or Node different from what the environment provides. Pinning versions in package.json or pyproject.toml plus adding the missing Nix package to replit.nix fixes the vast majority of these.
Deployment 502s
A 502 on a *.replit.app URL typically means the app crashed on boot or exited immediately without opening its listen socket. Open the Deployment logs and look for the traceback — it is almost always in the first ten lines. Common causes: a missing environment variable, a database connection string that points at the wrong place, a port mismatch (the app listens on 8080 but Replit is routing 3000), or a permissions error trying to write outside the writable directory. If the crash only shows up under load rather than on boot, promote to Reserved VM to eliminate cold-start races that Autoscale surfaces.
Preview URLs 502-ing
The *.replit.dev preview URLs served from the workspace go to sleep when the Repl hibernates. If you share a preview URL with a colleague and it 502s, that is almost always the reason. Two fixes: open the workspace tab yourself to wake the Repl, then re-share, or — for anything you care about staying live — promote the app to a Deployment. Preview URLs are for previewing during development, not for production traffic; treating them as free hosting is the single most common footgun new Replit users hit.
Custom domain no longer resolving
If your custom domain suddenly starts serving a Replit error page or a browser DNS error, check three things in order. One, is the DNS record still pointing at Replit's edge? Registrars occasionally reset records during migrations. Two, has the domain's TLS certificate expired or failed to renew? Certificates renew automatically via ACME but occasionally get stuck; removing and re-adding the domain in the Deployments settings forces a fresh issuance. Three, is Replit itself in an edge-routing incident on the status page? All three are quick to check.
Database connectivity errors
If your app suddenly cannot reach its Postgres or Redis, walk the network path. If you use Replit's managed Postgres (Neon under the hood), check both status.replit.com and Neon's status page — the two are separate services with separate incidents. If you use an external managed database, check that provider's status page directly. Verify the connection string in Secrets matches the one in the provider's dashboard: rotated credentials that were never updated in Replit's Secrets tab are a surprisingly common cause of 'sudden' outages.
When to open a support ticket
Open a ticket when the problem is reproducible, isolated to Replit, and not already on the status page. Include the Repl URL, the Deployment ID if relevant, a copy of the last hundred lines of logs, and a clear description of expected vs actual behaviour. Do not open a ticket for a live incident already listed on status.replit.com — the team is already working on it and support cannot accelerate the fix. During an incident, subscribe to the status page's email or webhook feed instead and get on with something else.
Building a personal incident checklist
Every developer who ships on Replit eventually accumulates a personal ordered checklist for outages. Something like: check status.replit.com and replit.health, check the Deployment logs, check the Deployment Secrets, check the run command and listen port, check the DNS and TLS, then finally check upstream provider status pages. Write yours down. When something goes wrong at 11 p.m. you will not remember the order under pressure, and a checklist you can run top-to-bottom in five minutes is worth a lot more than trying to reason from first principles while a customer is waiting. Update the checklist every time an incident reveals a new failure mode; that is how a personal playbook becomes a team playbook.
Post-incident hygiene
After the fire is out, spend fifteen minutes writing down what happened. Timestamp, symptom, root cause, fix, and what you would do differently. It does not have to be a formal post-mortem — a paragraph in a Notion doc or a pinned message in your team's Slack is enough. The point is that Replit incidents cluster around a handful of failure modes (missing Deployment Secrets, Nix package gaps, egress spikes, hibernating previews shared as prod) and if you write them down you stop paying for the same lesson twice. Over a year of shipping, that habit is worth an outsized number of hours you will not have to spend debugging under pressure.