Most problems in Caffeine fall into a few familiar categories: a build that didn't do what you expected, an app that isn't loading, credits that seem to be missing, or a feature that isn't showing up. This article covers the most frequently reported issues and what to do about them.
The AI built the wrong thing
The AI builds from your description. If the result isn't what you wanted, the most effective fix is usually to be more specific in your next message. Vague instructions produce generalized results; precise instructions produce precise results.
What to try:
- Describe what's wrong with the current version, not just what you want instead. For example: "The confirmation message shows the wrong date — it should show the date of the booking, not today's date."
- If the result is far off, try breaking the feature into smaller steps rather than asking for everything at once.
- If the AI repeatedly misunderstands a specific feature, try rephrasing it from a different angle.
- Try using Guided mode — it asks you clarifying questions before building, which can surface misunderstandings before they become a build you need to undo.
You cannot undo a build, but you have several options. You can ask the AI to reverse a specific change by describing what the app looked like before. Or you can revert to a previous draft version — either by clicking the Revert to version N button on a past build in your chat history, or by opening the version history panel (click the version badge in the top-right corner of the app preview panel) and reverting from there. Note that you cannot revert to a version older than the one that is currently live — this protects your live users' data.
My project used to work but now I can't build or deploy
If your project was created a while ago and has stopped working — builds fail, deploys get stuck, or the AI seems unable to make changes — this may be because the project is on an older format.
Caffeine now automatically migrates older projects to the current toolchain when you open them — restructuring older formats, migrating 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.
If your project has been completely stuck, try opening it and sending a simple prompt. The migration should run automatically. For the full details on what the migration does and what to expect, see Migrating Older Projects. If it still doesn't work, contact support with your project ID.
Even if your project isn't on an older format, you may notice that large or complex projects build more reliably now. Every build starts with a fresh scan of your project, and each specialist agent gets only the context it needs — so the AI doesn't lose track of your app regardless of how many drafts you've been through.
The build is taking a long time
Builds typically complete within a few minutes. You can check what's happening by expanding the build progress panel — it shows the current task checklist with status indicators for each piece of work.
If a build seems stuck:
- Send "what's the current status?" or "are we stuck?" to the AI
- Use the stop button to halt the build and try a different approach
- If nothing responds, refresh the page — the build may have completed while you were waiting
If the underlying container running your build has stopped unexpectedly, Caffeine detects this automatically and marks the build as failed within a few minutes — you do not need to wait or take any action. Any credits held for that build are released back to your account.
If a build is still stuck after several minutes and has not been marked as failed, contact support.
My app isn't loading
If your app shows a blank page or an error when you try to open it:
Check whether it's deployed. Your app must be in Live mode to be accessible via its public URL. If you're still in Draft mode, the app isn't live yet. Switch to Live mode and deploy.
Check whether it's your draft or the live version. The draft preview inside Caffeine may behave differently from the deployed live version. Always test the live URL before reporting a bug.
Wait a moment after deploying. It can take 30–60 seconds for a newly deployed version to become reachable. Reload the page after waiting.
Try a different browser or incognito mode. Browser extensions, cached data, or stored credentials can sometimes interfere with loading. If the app works in a clean browser session, the issue is likely local to your browser.
If the screen is fully blank or white, collect the error and share it with the AI. A blank screen usually means your app started loading but hit a JavaScript error that stopped it. Caffeine cannot see this error on its own — it happens inside your browser while your app runs. Open your browser's developer console, copy the red error messages, and paste them into the project chat so the AI can read the exact failure and fix it in the next build. For step-by-step instructions for every browser, see Fixing a Blank or White Screen.
If you see a temporary unavailability error (such as IC0508 or "Service temporarily unavailable"). This can happen when a canister briefly runs low on cycles. Caffeine automatically tops up cycles — wait and reload your app. You do not need to contact support or ask for a manual top-up. If the error does not fix itself after half an hour, contact support. See Understanding Canister Cycles for details.
My app is losing data or behaving unexpectedly after a new build
Each build is a full replacement of your app's code. The AI regenerates the backend from the current specification, which can sometimes change how data is structured or stored.
Caffeine automatically handles data migration when the AI changes your data model — existing data is carried forward into the new structure. This is built in and does not require any action from you.
If your app's data seems wrong after a build, describe the problem specifically in the chat. For example: "After the last build, my existing posts are no longer showing up — please check the data migration." The AI can inspect and fix the migration in the next build.
I'm out of credits and don't know why
Credits are consumed by each build. If your balance dropped unexpectedly:
- Check how many builds you started and how many times you deployed. Build credits (2 per build) are held when a build starts — not after it finishes. If a build fails, those credits are released back to your account. Go Live credits (4 per first go-live) are charged when you click Go live; they are released back automatically only if Go Live could not start. If you see a Go live failed message, the charge typically still applies.
- Free users receive 10 welcome credits at signup, valid for 30 days. If those credits are used or expired, you will not receive automatic refills.
- Subscription credits expire at the end of your billing period. If you recently renewed, you should have a fresh allocation.
- Top-up credits (purchased separately) expire 6 months after purchase. Voucher credits expire 3 months after redemption.
Credits are spent in this order: welcome credits first, then subscription credits, then top-up or voucher credits. See Understanding Credits for the full order.
If you believe credits were consumed incorrectly, contact support with your account email and the approximate time the credits disappeared.
A feature that should be available on my plan isn't working
Some features require a paid plan (Host or Studio), and some require Studio specifically. If you're on a paid plan but a feature isn't behaving as expected:
- Make sure your subscription is active. Visit your account settings to confirm your plan status.
- Some features (email sending, analytics) are provisioned at deploy time. If you upgraded and then immediately tried to use the feature without rebuilding or redeploying, try triggering a new build.
- If you recently upgraded, allow a minute for the change to propagate before testing.
If the feature still doesn't work after a rebuild, contact support.
I can't log in, or my projects are missing
Caffeine uses Internet Identity — a passkey-based system with no passwords. Login issues are almost always caused by being on a different device or browser than usual, or not having devices linked.
See Logging In and Managing Your Identity for a full explanation and how to fix it.
If you can't log in to the admin account of your own app specifically, see Becoming Admin of Your Own App.
My message was blocked by the safety system
Caffeine screens every prompt for harmful content and prompt injection attempts. If your message is blocked, no build runs and no credits are charged. The blocked message is automatically removed from the conversation history, so it does not affect your next prompt — just rephrase and try again.
For a full explanation of how the safety system works and what to do if rephrasing does not help, see Content Safety and Blocked Messages.
I'm not seeing browser notifications from Caffeine
If Caffeine is not notifying you when a draft is ready, the most common causes are blocked browser permissions, OS notification settings, Focus mode, or the browser putting the tab to sleep in the background.
See Browser Notification Troubleshooting for the full step-by-step guide.
My changes aren't showing up for users
If you made changes but users on the live URL are still seeing the old version:
- Confirm you published the new version. Editing in Draft mode doesn't affect what users see — you must switch to Live mode and deploy.
- After deploying, wait 30–60 seconds and reload. New deployments take a moment to propagate.
- Ask the user to do a hard refresh (Cmd+Shift+R on Mac, Ctrl+Shift+R on Windows). Their browser may have cached the old version.
Frequently asked questions
Can I undo a build?
There's no single undo button, but you can revert to any previous draft version. Use 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 in the top-right corner of the app preview panel. You can also ask the AI to reverse a specific change: "The last build removed the search bar — please add it back." Note that you cannot revert to a version older than the one that is currently live — this protects your live users' data.
Why did my draft disappear?
Drafts are tied to a specific version of your app's specification. If the AI built a new version, the previous draft was replaced. You cannot recover a draft that has been overwritten by a new build.
The AI keeps making the same mistake. What should I do?
Try rephrasing the request from scratch. If the AI has "learned" an incorrect behavior through several rounds of iteration, starting a new approach in your message — without referencing the previous failed attempts — can help it generate a clean result. You can also try stopping the build and re-prompting with a different approach.
My app worked yesterday and now it's broken. I didn't change anything.
If you didn't trigger a new build, the app code is exactly the same. More likely causes: a browser update changed how the app renders, or cached data in your browser is conflicting. Try opening the app in a private/incognito window. If it works there, clear your browser cache.
My app opens to a blank white screen. How do I fix it?
A blank screen means the app loaded but hit an error that stopped it before anything appeared. The fastest fix is to capture that error and paste it into the chat: open your browser's developer console, reload the page, copy the red error messages, and paste them to the AI. Caffeine cannot see this error on its own because it happens inside your browser, so sharing the text is what lets the AI diagnose and fix it. Full step-by-step instructions for every browser are in Fixing a Blank or White Screen.
I see an error message I don't understand. What should I include when contacting support?
Include: your project ID, the URL of the app, what you did before the error appeared, the exact error message or a screenshot, and your account email. If the app is blank or broken, also include the errors from your browser's developer console — see Fixing a Blank or White Screen for how to copy them. The more context you provide, the faster support can identify the issue.