You gave Replit Agent a task, it rewrote half your project, and now the app throws an error it never threw before. Or it worked in the editor but refuses to run after deployment. Or three months of daily prompting has left you with something that works most of the time, in ways you cannot fully explain.
Replit breaks in specific, predictable ways. It is a cloud-based environment that runs your app in a container, which means some failures look identical to local development problems but have completely different causes. Here is how to read what went wrong, what you can recover yourself using Replit's built-in tools, and when the damage is structural enough that a proper audit is the faster path.
Why Replit Agent breaks things differently
Most vibe-coding tools run in browser sandboxes with their own deployment pipelines. Replit is different in two ways that matter: first, it runs your actual code in a real cloud container, not a browser simulation. Second, Replit Agent edits your real project files, not a preview layer. When Agent makes a mistake, it breaks the real app.
The container model creates a specific class of error that catches people out constantly. Your Replit editor runs in a "development" container. Your deployed app runs in a separate "production" container. They do not share state. Secrets you set in the Secrets tab during development are not automatically in production. A port your app binds to locally may not match what deployment expects. Configuration that works when you click Run may not survive the cold start of a deployment.
Replit Agent also has the same context window limitations as every other AI coding tool. Early in a session, it has full visibility of what it is doing. Long sessions produce the same pattern seen with Cursor, Bolt, and every other tool: edits that are locally correct but globally inconsistent, because the model lost track of constraints it set up earlier. The difference is that Replit's Checkpoints (saved automatically during Agent sessions) are the rollback mechanism, and not everyone knows they exist.
Diagnose it: six symptoms, six causes
Find your symptom in the left column. The middle column explains what is almost always underneath it. The right column tells you honestly whether you can fix it yourself.
| Symptom | What it usually means | Can you fix it yourself? |
|---|---|---|
| App runs in the editor but crashes after deployment | Missing secrets in production. Your development container has Secrets you set manually. Your production deployment does not unless you explicitly added them to the deployment environment. The app starts, tries to connect to a service, finds no credentials, and crashes. | Yes. Open Deployments, find the environment variables section, and add every key from your Secrets tab. Then redeploy. |
| Cannot find module / module not found error | Agent added an import or require for a package that is not installed, or renamed a file without updating the imports that referenced the old name. Also common: Agent installed a package in the Shell but forgot to add it to package.json, so the next container start cannot find it. |
Yes. Run npm install <package-name> in the Shell if the package exists, or check whether Agent renamed the file the import expects. If package.json is missing the package, add it and run npm install. |
| Port or networking error on deployment | Your app is binding to a hardcoded port (3000, 8080, or similar) instead of reading from process.env.PORT. Replit's deployment layer assigns the port dynamically and expects your app to use it. A hardcoded port works in development and silently fails in production. |
Yes. Find where your server starts and replace the hardcoded port with process.env.PORT || 3000. Redeploy. |
| App was working, then Agent made a change, now nothing works | Agent's last session introduced a regression across multiple files. Because Replit does not use git by default, there is no git diff to read. But Replit saves Checkpoints automatically during Agent sessions. |
Yes, via Checkpoints. Open the History panel in your Repl, find the Checkpoint from before the last Agent session, and restore it. You lose the Agent's changes, but you recover a working app. |
| API key or secret visible in the browser's network tab | Agent put a secret key directly in frontend code or called a third-party API from client-side JavaScript. Anyone who opens browser developer tools can read it. This is not just a bug: it is a security breach if the key has write access to anything. | Partially. You can move the API call to a server-side function or Replit's backend. But the key is compromised the moment it was visible in production. Rotate it immediately, before fixing the code. |
| App works but data is available to anyone who knows the right URL | Agent built API routes without authentication checks. If your app has a database and Agent wrote the query routes, it is common for them to return data with no session check - the route assumes the caller is authenticated but never verifies it. | Only if you understand the auth model. If you are not sure how your authentication works or whether it covers all routes, this needs a proper audit. Guessing at auth fixes creates the illusion of security without the reality. |
The Checkpoint rule
If Replit Agent has made three attempts to fix the same error and it is still broken, stop prompting and roll back to a Checkpoint.
Replit creates Checkpoints automatically at key moments during Agent sessions. They are snapshots of your entire project at that point in time. You can find them in the History panel of your Repl. When an Agent session goes wrong, rolling back to the Checkpoint before that session started gives you a clean slate to work from - faster than continuing to prompt on top of broken code.
The mistake most people make is treating more prompting as the solution to a problem that more prompting caused. Once you have exceeded a session's effective context window, the Agent is editing with a partial and compressed view of what it did earlier. Each new prompt compounds the drift. A Checkpoint rollback followed by a narrower, more specific Agent session is almost always faster.
The four-minute triage you can do right now
Before you pay anyone, run these four checks. They use what Replit already gives you.
- Check your Secrets vs your deployment environment. Open the Secrets tab in your Repl. Write down every key there. Then open Deployments and check the environment variables section. Anything missing from deployments that exists in Secrets is a likely cause of "works in editor, fails in production." Add the missing keys and redeploy.
- Search for hardcoded ports. In the Replit file explorer, use the search function to find your server startup code. Look for any line where a port number appears as a literal number rather than as
process.env.PORT. This is a five-second fix that resolves a wide class of deployment failures. - Check History for the last working Checkpoint. Open the History panel. Replit labels Checkpoints with timestamps and Agent session notes. Find the last Checkpoint that corresponds to a time when your app was working. You do not need to restore it yet - just identify it so you know where you can roll back to.
- Search for API keys in frontend files. Open the Shell and run:
grep -r "sk-\|Bearer \|api_key\|API_KEY" --include="*.js" --include="*.jsx" --include="*.ts" --include="*.tsx" src/ public/ 2>/dev/null(adjust the directory names for your project). Any match in a frontend file means a key that is visible to anyone who views your app. Rotate those keys immediately and move the calls server-side.
If checks one and two resolve the issue, you are in good shape: these are operational mismatches, not structural problems. If check four returned matches, treat those as urgent security issues regardless of whether the app is otherwise working.
When a Checkpoint rollback is not enough
A Checkpoint takes you back to an earlier version of the files. It does not fix patterns that were already in the codebase before the session you are rolling back from. These are the situations where rolling back leaves you at a codebase that was already broken in ways you did not fully see:
- Authentication added as an afterthought. Replit Agent commonly adds login screens and session handling as features when asked, but without designing an auth model first. The result protects some routes and misses others, with no consistent policy an audit can validate quickly.
- API secrets in frontend code. A pattern that appears in Replit projects more than any other platform: Agent called a third-party API directly from client-side JavaScript because that was the path of least resistance. Every user of your app can read your API key using browser developer tools. If the key has write or billing access, this is an active breach.
- Database with no access control. If Agent built a database and query routes without setting up row-level security or server-side auth checks, any user who can find the API endpoint gets all the data. This is not theoretical: it is a common pattern in Replit-built apps that reach real users.
- An architecture nobody fully understands. Three months of Replit Agent sessions with no documentation and no consistent structure leaves a codebase where fixing one thing reliably breaks another, and the only way to understand it is to read every file.
If any of these apply, you are in rescue territory. Checkpoint rollbacks and more prompting are not the right tools. Read our vibe code rescue service page for how we approach it. Built with a different tool? The same underlying patterns appear in Bolt, Lovable, Cursor, and v0 apps, with variations specific to each platform's deployment model.
What rescue work actually costs
Honest numbers. Replit-built apps that need to reach production typically land somewhere in the USD 2,500 to 6,000 range for a standard rescue engagement. Replit projects tend toward the lower end of that range compared to Cursor projects, because the Checkpoint history gives auditors a clearer picture of what each Agent session did, and Replit apps are usually younger (people move off Replit faster when they hit production constraints).
What moves the cost is the security state when you arrive. API keys in frontend code mean a rotation exercise across every connected service before the code work begins. No authentication model means designing one from scratch, not patching an existing one. No test coverage means the audit starts from zero with no safety net.
The cheap alternative is a generalist who patches the immediate error without understanding whether the routes that serve it are authenticated, or whether the key it uses should be server-side. Replit projects that skipped the security foundations are particularly exposed to this class of fast-but-wrong fix.
What a professional rescue actually does
The order is not optional. Building features on a broken foundation breaks the features. A proper rescue runs in this sequence:
- Full audit first. Read the entire project before touching anything. Map the auth model, data access patterns, secrets locations, and deployment configuration. The findings go into a fixed-scope report you approve before we start the work.
- Secrets moved to the correct layer. Any key that belongs server-side is moved server-side. Any key visible in frontend code is rotated immediately and then moved.
- Authentication designed and enforced. A consistent auth model applied to every route that needs it, at the server layer, not just the UI layer.
- Data access controls. Query logic that verifies who is asking before returning data. No route that trusts the caller without checking.
- Proper deployment configuration. Production environment variables, port handling, and a deployment setup that matches how Replit actually works.
- Test coverage and CI. Critical paths covered by tests. A pipeline that runs them on every change, so future Agent sessions cannot silently break something that was working.
- Then your feature list. Deliberately last. On ground that can hold it.
This is the approach we take on our vibe code rescue service, which covers apps built with Replit, Cursor, Bolt, Lovable, v0, and similar tools. If the scope you need is ongoing support rather than a one-time rescue, read about our Snowball retainer.
Frequently asked questions
Can Replit Agent fix its own broken code?
Sometimes, for small isolated errors. Replit Agent works within a session context and can often fix syntax errors or missing imports when you describe the error message precisely. Where it struggles is with problems it created across multiple files in an earlier session - the context from that session is gone, so it is working blind. If Replit Agent has already made three attempts to fix the same error and the error persists, stop and use a Checkpoint to go back. More prompting does not fix a structural problem.
Should I roll back to a Checkpoint or keep prompting Replit Agent?
Roll back. If your app was working at a Checkpoint before the last Agent session, use that Checkpoint. More prompting on top of broken code compounds the problem because the model is making edits without full visibility of what earlier sessions did. Find the last Checkpoint where everything worked (Replit saves these automatically during Agent sessions), restore it, and start a new, narrower Agent session from there.
Why does my Replit app work in the editor but fail after deployment?
Usually secrets. In the Replit editor, environment variables you set in the Secrets tab are available immediately. When you deploy, Replit creates a separate production environment that needs its own copy of those secrets. Open your deployment settings and add every key from your Secrets tab to the deployment environment variables. A secondary cause is that your app is binding to a hardcoded port instead of reading from process.env.PORT, which Replit requires for deployed apps.
When do I need a professional rescue rather than a Checkpoint rollback?
A Checkpoint rollback handles session-level mistakes. A professional rescue is for structural problems that were already in the code before the latest session made them visible: authentication that was added as an afterthought and covers some routes but not others, database queries that expose data to any user who knows the right URL, API keys embedded in frontend code that anyone can read with browser developer tools, or a codebase that has grown through months of prompting without anyone understanding how the pieces connect. These problems do not go away when you roll back.