A build failure means Caffeine was unable to generate working code for your app. Unlike a deployment failure — where the code was built but could not be published — a build failure stops earlier: the app was never successfully generated in the first place.
How Caffeine handles errors during builds
Caffeine's build system checks for errors at every stage, not just at the end. Backend code is compiled before frontend work begins. Frontend code is type-checked after every round of changes. The Quality agent validates the finished app against your original requirements and runs visual tests.
When an error is caught mid-build:
- The system retries automatically. Failed tasks are dispatched again with the error details and any learnings from the failure. The retry gets a fresh context, so it isn't fighting through accumulated mistakes.
- The system can go back. If a later stage discovers a problem with earlier work — for example, the frontend needs a backend endpoint that doesn't exist — the Composer can dispatch the backend engineer again in a later wave to add it.
- Optional tasks can be skipped. If a non-critical task fails (such as visual testing), it is marked as skipped and the build continues.
If a critical task fails after retrying and the app cannot be deployed, the build is cleanly discarded rather than left in a broken state. You'll see which task failed in the build progress panel.
Backend build failures
The backend is the most common source of build failures. Caffeine writes your backend in Motoko, a language designed specifically for apps running on the Internet Computer. When the AI generates Motoko code that does not compile, it automatically attempts to fix the errors and retry.
Common reasons the backend fails:
- The change you requested was more complex than the builder could complete in the available attempts
- You tried to change how data is structured — adding or modifying fields in a record type — which requires careful, incremental changes
- The project uses older data structures that need migration (see below)
Frontend build failures
Frontend failures are less common. The frontend is built in React and TypeScript, and compile checks run between every coding wave. When a frontend error is caught, the system retries with the error details. Most frontend compile errors are resolved automatically.
What to do when a build fails
If a build fails, you have several options:
Try re-prompting. Describe the same change in different words, or break it into smaller steps. A simpler, more focused prompt often succeeds where a broad one failed.
Revert and try again. You can revert to a previous version in two ways: click the Revert to version N button on a past build in your chat history, or open the version history panel by clicking the version badge (e.g., "v5") in the top-right corner of the app preview panel. From there, you can browse all previous versions and revert to any of them. Note that you cannot revert to a version older than the one that is currently live — this protects your live users' data. Reverting is often the fastest path forward — don't try to fix forward from a broken state.
Check the build progress. Expand the build progress panel to see which specific task failed. This can help you understand what went wrong and how to adjust your prompt.
Ask Caffeine what happened. Send "what went wrong with the last build?" and the AI can explain what it tried and why it failed.
Projects that were stuck on older versions
If your project was built a while ago and you haven't been able to iterate on it, Caffeine now automatically migrates older projects to the current toolchain when you open them — restructuring older formats, migrating Motoko data structures, and upgrading internal components to published packages.
If migration is needed, the AI handles it as its first task before addressing your request. You may see it creating migration files and verifying compatibility before starting on your actual changes. For the full details, see Migrating Older Projects.
The most important habit: build incrementally
Most painful build failures happen when errors go unnoticed across many versions. A common pattern is: something breaks at version 10, the user keeps building, and only discovers the issue at version 20. Reverting now means losing everything from versions 11 through 20.
Test your draft after every build. Before sending your next message, open the draft and check that the thing you just built actually works. This takes less than a minute and catches errors at the version where they were introduced.
Keep each prompt focused on one thing. The more a single prompt changes, the more things that can break and the harder it is to identify the cause. Small prompts mean small failures and easy recovery.
Treat a revert as a normal tool, not a last resort. Reverting to a working version and re-prompting from there is almost always faster than trying to fix broken code through the AI chat.
Frequently asked questions
Do failed builds cost credits?
No. Credits are charged when the AI starts a build, but if the build fails for any reason — including a compile error, a container failure, or the session timing out — the credits are automatically refunded to your account. The net result is no cost to you.
I reverted but the same error keeps happening. What now?
Try reverting further back — to a version before the problematic change was introduced. If the error appears even on a very early version, or on a brand new prompt, contact support with your project ID and the error message.
My project is too complex to build reliably. What are my options?
Caffeine's V3 architecture handles complex projects significantly better than before — each build starts with a fresh scan of your project and each specialist agent gets only the context it needs. Projects that previously hit context limits may now build reliably. If you're still hitting issues, the recommended path is to export to GitHub and continue development using external tools or a developer. For more detail, see What Caffeine Can and Cannot Build.