Bolt app stuck? How to get your project moving again

When people say their Bolt app is stuck, they usually mean one of three things. The AI has stopped making useful progress, the project will not build at all, or it runs inside Bolt but nowhere else. Each has a different cause and a different way out. This page helps you work out which one you have, get a safe copy of your code, and decide whether to keep going yourself or hand it to someone who finishes projects for a living.

Why Bolt projects get stuck

The project has outgrown the AI's context

Bolt sends your project files along with each prompt so the AI knows what it is editing. Early on that works well. As the app grows, every message carries more context, which uses more tokens, and the model may no longer see all the relevant code at once.

You will recognise the signs: the AI forgets decisions made earlier, creates a second version of a component that already exists, edits the wrong file, or reintroduces a bug it fixed an hour ago. Meanwhile your token balance drains faster than before.

What helps:

• Write short prompts that name the exact file or screen to change.
• Ask for one change per prompt, then test before the next one.
• Break very large files into smaller ones so less needs to be sent each time.
• Use Bolt's option to exclude files from the AI's context (check Bolt's current help pages for how this works on your plan).

The build is broken

Sometimes the preview shows a red error overlay, or the terminal panel in Bolt fills with errors and nothing loads. Common causes are a package imported in the code but never installed, two packages that need different versions of the same library, or TypeScript errors.

That last one catches many people out. In a Vite project, the development server shows your app even when there are type errors, but the production build command often runs a type check first and stops on the first problem. So an app that "works" in the preview can fail the moment you try to deploy it.

When you look at the terminal output, copy the first error rather than the last. Later errors are often side effects of the first one.

It works in Bolt but not anywhere else

Bolt runs your project in StackBlitz WebContainers, a Node.js environment that lives inside your browser tab. It is clever and fast, but it is not a server on the internet. That leads to a few predictable surprises:

• Nothing keeps running when the tab is closed. Scheduled jobs, background workers and long-running servers need real hosting.
• Data stored in memory or in the browser is not a database. If the app saves data in local storage or an in-memory list, each user only sees their own copy and it can vanish. Real apps need a hosted database such as Supabase or Firebase.
• Environment variables do not travel with the code. Keys in Bolt's .env file must be added again in your host's settings.
• The two environments are not identical. A package that behaves one way in a WebContainer can behave differently on a Linux server.

Get your code out of Bolt before anything else

Before you spend more tokens, make a copy of what you have. Bolt lets you download the project and connect it to GitHub. Do both: the download is your personal backup, and the GitHub repository is what you will share with a developer later.

Then check the copy:

• It contains package.json, a lock file such as package-lock.json, and the source folders.
• No .env file with real keys was pushed to GitHub. If one was, especially in a public repository, create new keys in each service and switch the old ones off.
• Paste config files or suspicious code into the Secret Leak Scanner to look for keys you did not know were there.
• If the repository is public, run the Repo Health Check for a quick picture of its state.
• Paste package.json into the Dependency Freshness Check to spot outdated or deprecated packages.

Deploying outside Bolt

Bolt's built-in deploy option is enough for many projects. When you need more control, such as a server, a custom build or a particular region, you will move to your own hosting. The basic steps are the same on most platforms:

1. Pick a host that matches the app. A front-end-only Vite app can go on static hosting; an app with its own Node.js server needs a host that runs one.
2. Set the build command (often npm run build) and the output folder (dist for a default Vite app).
3. Add every environment variable the app uses.
4. Match the Node.js version you used in Bolt.
5. Add your domain and update any login or payment settings that mention the old address.

If the build fails on the host, read the log from the top, exactly as you would in Bolt's terminal.

What a developer will look at first

A developer taking over a Bolt project normally starts outside Bolt. They clone the repository, do a clean install and run the production build on their own machine to see the full list of errors. They then look at where data actually lives, which API keys are used from the browser, and whether there is any server code at all.

They will also look for leftovers from many rounds of prompting: duplicate components, unused files and half-finished features. Removing these often makes the app easier to work on, whether that continues in Bolt or in a normal code editor. Expect them to tell you which of those two routes they recommend and why. The guide on why Lovable, Bolt and v0 apps break in production covers the same ground from the technical side, and the prototype to production checklist shows what usually remains after the build works.

When to stop prompting and get help

It is time to get another pair of hands when the same bug keeps coming back, the token cost of each fix is climbing, you need a feature the browser environment cannot run, or you are about to take payments or store personal data. A related page, Lovable app not working, covers similar ground for Lovable projects if you have used both tools.

Post your Bolt project as a takeover

You can post your stuck Bolt project for free. Say that it was built with Bolt, describe what works in the preview and what you need on a live site, mention whether the code is on GitHub, and paste the first build error if you have one. If your notes are messy, the AI Listing Writer can turn them into a clear draft, and the guide on writing a takeover listing that gets responses shows what developers look for. TakeoverWork connects you with people who rescue projects; you choose who to talk to and agree the work and payment with them directly.