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
Separate the Replit project you edit from the published app and confirm each environment's configuration. Agents can modify project files; preserve changes and review their effect before publishing.
Development and published projects can use different configuration or credentials. Replit provides production-secret settings in Publishing. Review only values required by the published app; do not copy all development credentials indiscriminately.
An agent may help with an isolated, reproducible bug. Keep the change small and verify it against a saved baseline. Repeated unsuccessful patches are a reason to investigate the logs, dependencies and access controls, not proof of a specific context-window failure.
Diagnose it: six symptoms, six causes
Use this table to identify possible causes and useful checks. Symptoms can have more than one cause; confirm the diagnosis with logs and a reproducible example.
| Symptom | Possible cause to investigate | Can you fix it yourself? |
|---|---|---|
| App runs in the editor but crashes after deployment | A missing or incorrect production secret, dependency, runtime setting or database connection may cause a deployment failure. Confirm the first published-app log error rather than assuming secrets are always the cause. | Review the required production credentials in Publishing settings, using the intended production services. Confirm access and test the published app after a controlled change. |
| Cannot find module / module not found error | Possible cause: 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 | A mismatch between the app's listen address, configured port and publishing requirements can prevent deployment. Check the selected deployment type and current runtime settings. | Check the app startup command and deployment requirements before editing the listening port or address. Test the corrected configuration in an appropriate environment. |
| App was working, then Agent made a change, now nothing works | Recent changes may have introduced a regression. Replit checkpoints and Git history can help compare project states; check what was saved before choosing a rollback. | Use checkpoint history to identify the last known working state. Preserve current changes and data first. Review rollback options: restoring code does not automatically restore the production database. |
| API key or secret visible in the browser's network tab | Possible cause: 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 | Possible cause: 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 repeated attempts are not resolving the same error, pause new changes. Save the current state and identify a known working version. Inspect what changed before deciding whether to revert, repair or seek help.
Replit checkpoints can help recover project files and state. Rollback options matter: database changes are not restored by default, optional rollback concerns the development database, and production restoration is separate. Review what will be discarded and keep backups before proceeding.
Incomplete instructions, incompatible edits, missing dependencies or stale assumptions can cause regressions. Session length alone does not diagnose the cause. Preserve the current state, read the logs and compare the last changes against the previously working version before making another patch.
The four-minute triage you can do right now
Before you pay anyone, run these four checks. They use what Replit already gives you.
- Compare required production configuration. Review Publishing settings and the credentials actually required by the published app. Keep testing and production services distinct where intended. Never paste secret values into a troubleshooting chat or copy every development key by default.
- Check the startup and port configuration. Compare the application's listen address and port with its publishing type and runtime requirements. Use the deployment log to confirm a mismatch before changing code.
- 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.
- Review frontend credentials safely. Search locally for suspicious credential values without copying them into chat or shared logs. Variable names and publishable keys are not proof of a secret leak. Identify the credential type; rotate actual exposed secrets and move privileged calls to a trusted server.
A resolved configuration issue is useful evidence but does not rule out other defects. A frontend search match needs classification: a variable name or publishable key alone is not an exposed secret. Prioritise any confirmed privileged-secret or protected-data exposure, then use our security checklist to review the remaining scope.
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.
- Privileged secrets in frontend code. Inspect actual credential values and privileges. A leaked secret needs rotation and an exposure review; a public identifier or publishable key alone is not evidence of a 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
There is no verified market-price dataset behind this guide. Request an audit-based quote that separates investigation, urgent security work, repair, testing, deployment and ongoing support. The tool used to build the app does not determine the price.
Actual privileged secrets in frontend code require rotation and an exposure review. Public identifiers and publishable keys are different. Cost also depends on missing access controls, affected integrations, test coverage and recovery needs.
Compare the proposed investigation, security checks, test coverage and handover rather than the supplier's location or job title. A low quote may exclude important work, while a high quote does not establish quality. Ask each supplier to explain its assumptions and exclusions.
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 in the correct layer. Identify actual privileged secrets, rotate exposed values and move privileged calls to trusted server infrastructure. Public identifiers are not treated as leaked secrets solely because they are visible.
- 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.
- Tests and CI. Check critical paths on proposed changes so covered regressions can be caught before release. Tests reduce risk within their coverage; they do not guarantee that every bug or production issue will be detected.
- Then your feature list. Deliberately last. On ground that can hold it.
General application support is scoped separately through our vibe-code rescue service. Snowball is our ongoing Shopify service, with priorities and delivery scope agreed upfront; it is not a general Replit app support package.
Frequently asked questions
Can Replit Agent fix its own broken code?
An agent may help with an isolated, reproducible error. Save a baseline, keep the change narrow and verify it. Repeated failures call for investigating the logs and changes; they do not establish a particular context-window cause.
Should I roll back to a Checkpoint or keep prompting Replit Agent?
Consider rollback when a saved state is known to work and the recent changes caused the failure. Preserve current work and data, review checkpoint scope, and test the result. Production database restoration is a separate operation, not an automatic consequence of restoring code.
Why does my Replit app work in the editor but fail after deployment?
Review the first published-app error and required production configuration. Replit has production-secret controls in Publishing; add only the intended required credentials. Also check dependencies, startup configuration and database access. A working editor session does not establish a production diagnosis.
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.