Guides & Tutorials
Troubleshooting Errors
Actionable steps to resolve issues when using Mocha
Building with Mocha gives you an AI pair-programmer that writes lots of code for you. That power comes with the occasional glitch: Code can be subtle to get right, and even AIs make mistakes which need to be fixed.
Our goal is to have Mocha fix everything for you, but our product is still not 100% perfect and sometimes you will need to help it out.
When something goes wrong, stay calm and follow the playbook below to get unstuck quickly.
Use Discuss Mode to chat through the problem first; once Mocha explains the root cause, switch back to Build Mode and ask Mocha to ‘fix what we just discussed’.
Checklist
Quick-Fix Checklist
1
Refresh the page
A hard refresh will clear any transient UI glitches.
2
Restart the sandbox
Click the restart button in the top-right corner.
This forces a clean build and often resolves state-related errors.
This forces a clean build and often resolves state-related errors.
3
Check your connection
Make sure you have a stable internet connection—Mocha runs partly in the cloud.
4
Use a modern browser
Mocha is build for the latest versions of Chrome, Edge, Safari and Firefox.
5
Open the logs panel
Press ⌘ B (or Ctrl + B on Windows) to toggle the realtime logs.
Look for stack traces or build errors—screenshots go a long way when asking Mocha for help.
Even if you’re not technical, the logs panel contains useful information you can use to share with Mocha support or with the AI (the AI can read it, just mention it).
Look for stack traces or build errors—screenshots go a long way when asking Mocha for help.
Even if you’re not technical, the logs panel contains useful information you can use to share with Mocha support or with the AI (the AI can read it, just mention it).Craft a Targeted Prompt Before Hitting “Fix”
It’s OK to try the “Fix with AI” button first, but if it doesn’t work the first time, it’s better to try to collect more information about the issue to help Mocha fix it more effectively.
- What you expected to see
- What you actually saw (include error text)
- Any steps that reproduce the issue
Strategic Approaches
- Restore a known-good version: [Version management]](/basics/versions) lets you roll back instantly. If you’ve spent multiple credits without progress, restoring and trying again with a more specific prompt is often a better approach.
- Iterate in small steps: Commit or preview after each change so you know exactly which edit introduced the bug.
- Watch your credits: Endless “try again” loops can be costly—change tactics instead.
Common Troubleshooting Areas
Troubleshooting generally falls into these categories:UI or Layout Glitches
- Use screenshots to explain visual bugs
- Prompt Mocha clearly with what is wrong with the UI
Prompt Misinterpretations
- Review your original instructions
- Break down complex requests
- Use examples to clarify intent
- Restore rather than building upon a bad version
Deployment Issues
- We’re working on making these better!
- Check the logs panel for errors.
- If the AI can’t fix it after a couple of attempts, contact support.
Scenario-Specific Guides
I see a blank page
I see a blank page
Most blank pages are caused by a runtime exception in the UI, and you’ll see an errors in the logs panel.
- Refresh the page to see if it resolves the issue.
- Open the logs panel and look for “Unhandled Error” messages.
- Check the browser console for React or Vite errors.
- Revert the last commit—did the page render again?
- In Discuss Mode ask: “The app renders blank because <error message>. Please identify the component and suggest a fix.”
All I see is a loading spinner
All I see is a loading spinner
- This is a silly mistake Mocha makes sometimes. We’re working on it!
- Just say “All i see is a loader on the home page, check the home page component”
I can't deploy
I can't deploy
- We’re working on making these better!
- Check the logs panel for errors.
- If the AI can’t fix it after a couple of attempts, contact support.
I don't see the right data in production
I don't see the right data in production
- Remember: there are different databases for the sandbox and production. Do you need to seed the production database (add data to it)? If so, tell Mocha!
- Discuss Mode and Mocha currently doesn’t have access to the production database, so it can’t fix things there. This is for security reasons. You need to explain the issue to Mocha in the chat panel clearly.
When to Contact Support
The quickest response you’ll get is by going to our Discord server and asking for help there. The Mocha team is active there, and many community members will also help you out.Contact Mocha support if you experience:
- Persistent error loops that can’t be resolved
- Critical functionality failures
- Security concerns
- Platform-wide issues
Remember: Mocha is here to help. If you’re stuck, don’t hesitate to:
- Use the Try to Fix button
- Switch to Chat-Only Mode
- Roll back to a working version
- Contact support if needed