When a build fails

Builds fail. The model misreads a file, a package will not install, a provider rate-limits you. Bookbag is built to make failures legible rather than to hide them: the error is shown to you verbatim, and the work already done is kept.

This page is the index of every message you can see.

What happens to your app when a run fails

Nothing is rolled back. Files the builder wrote before it failed stay written. Your app may be in a half-changed state — a component created but not yet used, an import pointing at a file that does not exist.

That is why the preview sometimes shows an error after a failed run. Two ways out:

• Send another message describing what is broken. The builder has the whole history and usually finishes what it started.
• Restore to before the run in version history. This puts every file back exactly as it was.

Get me unstuck

After a failed run, an amber card appears above the chat composer:

Get me unstuck Fresh attempt that reads the error first and verifies the fix.

Clicking it opens a dialog titled What is still wrong? with an optional field labelled Describe it (optional), showing the example e.g. the login button does nothing. You can leave it empty — that means "just try again".

This is not a retry. It starts a new run with a different brief, which the builder is given verbatim. The brief names the previous attempt, the error it produced, and what it claimed to have done, then orders it to:

1. Read the development server log and fix every compile error before anything else.
2. Read the files involved rather than assuming what they contain.
3. Verify the change actually works, and never report success on an unverified fix.
4. Finish or revert a half-applied change rather than leaving the app split.
5. Say exactly what is blocking it, if it genuinely cannot fix the problem, instead of calling it done.

In every other respect it is an ordinary run: same model, same credits, same step list.

If no build has ever run on the project, the button's request is refused with "There is nothing to rescue yet — start a build first."

Messages from the run itself

Message	What it means	What to do
You are out of credits. Your balance tops up monthly, or you can add your own AI key under Account → AI and build without credits.	Your balance was at or below zero when the run tried to start. Nothing was spent.	Wait for the monthly top-up, ask an administrator for an adjustment, or add your own key.
The run stopped because your credits ran out. What was built so far is saved.	The balance hit zero partway through. The run ends as done, not failed.	Same as above. Everything written is kept.
The run stopped after repeating the same actions without progress.	The builder called the same tool with the same arguments three turns running, twice.	Describe the problem more concretely. Naming the file often breaks the loop.
The run used all 60 steps. Send a follow-up message to continue.	The step ceiling. The run ends as done.	Send another message. The history carries over, so it picks up where it stopped.
The run was cancelled.	You pressed stop.	—
The server restarted while this run was in flight.	Bookbag restarted mid-run.	Send the message again.

Messages about the model

These appear when Bookbag cannot get hold of a model to run the build. None of them is your app's fault.

Message	Cause
Your <provider> key could not be read — re-add it under Account → AI, or deactivate your models to fall back to the platform model.	You have an active model of your own but its provider key cannot be decrypted or is not active. Bookbag will not quietly fall back to platform credits — see Your own AI key.
No active <provider> API key is configured. A platform admin can add one under Admin → Platform AI.	A platform model is active but its provider has no active key.
No models are configured yet. A platform admin can add a provider key and a model under Admin → Platform AI.	The platform catalogue is empty.
Models exist but none are switched on. A platform admin can activate one under Admin → Platform AI — it also needs a provider API key for that model's provider.	Every model is deactivated.
The active models cannot call tools, so the builder cannot read or write a file. A platform admin can activate one that supports tools (GPT-4o or Claude Sonnet, for example) under Admin → Platform AI.	The active model cannot call tools, which makes it useless as a builder.
<provider> returned <status>: <body>	The provider rejected the request. The provider's own response is included.
<provider> rate-limited and retries are exhausted.	Two retries were not enough. Wait a minute and try again.

Messages about the sandbox

Message	Cause
No free preview port in the configured range — archive an old project or widen sandbox.previewPortStart/End.	Local sandboxes only. Every port between 4100 and 4199 is taken. Archive a project you are no longer using.
npm install failed: followed by the install output	A dependency would not install. The last 3,000 characters of npm's own output follow.
The dev server exited immediately: followed by the log	The app crashed at start-up, usually because of a syntax error in a file just written. Restoring the previous version fixes it.
The sandbox dev server did not come up: followed by the log	The server did not answer within the readiness window — 60 seconds locally, 90 in the cloud.
The Daytona driver needs an API key: set DAYTONA_API_KEY or add one under Admin → Settings.	The installation is set to cloud sandboxes but no key is configured. An administrator's problem.
Sandbox <id> no longer exists.	The cloud sandbox was removed outside Bookbag.
Path escapes the project: <path>	The builder tried to touch a file outside your project. Refused.
<command> timed out after <n>s	A shell command ran past its limit — 3 minutes for ordinary commands.

Messages the builder sees and recovers from

These appear in the step list as <tool> failed. One of them on its own is not a problem; the builder reads the error and tries something else.

• edit_file failed: old_string is empty.
• edit_file failed: old_string not found in <path>. Read the file and match the text exactly. — the builder edited from memory instead of reading the file. It normally reads it and retries.
• edit_file failed: old_string appears <n> times in <path>. Make it unique or pass replace_all.
• run_command failed: no command given.
• run_command refused: the dev server is managed for you (use restart_dev_server), and long-lived/background processes are not allowed.

Denials, not failures

If you are a viewer in the organization that owns the project, you can read it but not change it. Starting a build comes back as:

You can view this project but not change it.

That is a permission answer, not a failure. See Roles and permissions.

Writing a prompt that fails less

• Name files. "The hero on app/page.jsx is too tall" beats "the top bit looks wrong".
• One change at a time. A run with one goal succeeds far more often than one with six.
• Describe the symptom, not the fix, unless you are sure. "Clicking Save does nothing" gives the builder more to work with than "add an onClick handler".
• Say what you already tried. The builder reads the whole history, so "the last change did not work because X" is useful information.

Next

• Version history — undoing a run that went wrong.
• The security check.