Common Issues & Fixes
Something's not working? Start here.
The app builds but looks wrong or broken
Symptoms: Preview loads but the UI is off — missing elements, layout broken, data not showing up.
Try:
- Describe what's wrong in the chat: "The table isn't showing any data" or "The sidebar is overlapping the main content"
- The AI can read your current code and fix UI issues quickly
- If the problem started after a specific change, consider restoring a version
Build failed — app won't deploy
Symptoms: You see a build error in the chat after asking the AI to make a change.
What happened: The AI made a code change that has a syntax error or broken import. The previous version of your app is still live and unaffected.
Try:
- Read the error message in the chat — it usually shows the exact file and line number
- Tell the AI: "The build failed. Here's the error: [paste it]" and it will fix it
- If you're stuck, ask: "What's causing this build error and how do we fix it?"
Data I added in preview isn't showing in production
This is expected behavior. Preview and production have completely separate data. Anything you add or delete in preview stays in preview.
If you want the same data in production, you'll need to add it again there, or ask the AI to pre-populate seed data on the next production deploy.
The app works in preview but breaks in production
Possible causes:
- A secret or API key was set up but the app hadn't been deployed to production yet when it was created — this resolves automatically on the first production deploy
- Production data is in a different state than preview (e.g. empty database vs seeded preview data)
Try:
- Deploy to production again — sometimes the first deploy after provisioning resolves the issue
- Check if the error mentions a missing API key or configuration
- Tell the AI what error you're seeing and where
The AI keeps changing things I didn't ask it to change
Try being more specific about the scope of what you want:
"Only change the button color. Don't touch anything else." "Add a search bar to the contacts page only — leave everything else as-is."
If the AI made unwanted changes, you can say "Undo that last change" and it will revert what it just did.
The AI is asking too many questions before building
Some questions are valuable (they prevent building the wrong thing). But if you want the AI to just start:
"I'll answer questions later — just build a reasonable first version now"
You can always refine after seeing the first cut.
The app is slow to deploy
The first deploy for a new project takes longer — the build system is setting up a fresh environment. Subsequent deploys are much faster.
If a deploy is taking unusually long (more than 2-3 minutes), try reloading the page. The deploy may have completed in the background.
I accidentally deleted important data
If you deleted records from the app UI: Storage data isn't included in version snapshots, so restoring a version won't bring back deleted data. If data recovery is critical, contact the platform team.
If you deleted files or code by mistake: Restore a saved version.
I hit the concurrent chat limit
Symptoms: A message like "maximum concurrent sessions reached."
Fix: Wait for one of your other chat sessions to finish, then try again. You can have up to 3 chat sessions running at the same time across all your projects.
A project is stuck — every new message returns "already in progress"
Symptoms: Sending a message immediately returns an error saying a chat session is already in progress, even though no AI response is running. Refreshing doesn't help.
What happened: Chat sessions hold a short-lived lock while the AI is working. If a background workflow crashed before it could release the lock, the project stays blocked until the lock expires (usually 60–120 seconds). In rare cases the lock can persist longer.
If you can wait: The lock has a TTL and will expire on its own. Wait a minute and try again.
If you need it cleared immediately: Contact a platform admin and ask them to clear the lock at Admin → Locks (/admin/locks). They can scan for all active locks and clear yours in one click — no deploy or code change needed.
For admins: Open /admin/locks, find the project in the Active Locks table, and click Clear. Or use the Manual Clear section if you know the project ID. Clearing removes the project-scoped lock and all per-member rate-limit slots. It does not affect chat history or project data.
Can my app show live updates without refreshing?
Not with persistent live connections (WebSockets) — the platform doesn't support them, so your app can't maintain an always-open channel to push updates to users in real time.
What does work:
- Polling — fetch new data every few seconds with
setInterval. Simple and reliable for most internal tools. - Server-Sent Events (SSE) — one-way push from your Worker to the browser. Works for live feeds, log streams, or progress updates.
Just ask the AI:
"Refresh the table every 10 seconds automatically" "Stream progress updates to the page as the job runs"
How do I send email from my app?
There's no built-in email component. For email, use a third-party service with your own account:
- Resend — simple API, generous free tier
- SendGrid — widely used, Twilio-owned
- Postmark — reliable transactional email
The AI can wire any of these up via the REST API proxy component. Just ask:
"Send an email via Resend when a new approval request is submitted"
You'll need to set your API key as a secret. The AI will guide you through it.
For SMS, use the Twilio integration component — it's built in.
I closed the browser while the AI was working
Any file changes the AI had already written are saved and will deploy in the background — you don't lose partial work. What you do lose is the AI's incomplete response text: if it was mid-message when the tab closed, that text won't appear in the chat history.
When you reopen the project, check the preview to see what state the app is in. If the deploy completed, you'll see the updated version.
My background job isn't running
Check the basics first:
- Make sure the job is
"enabled": trueinsrc/jobs/cron.json - Make sure you deployed after your last change — jobs are registered at deploy time, not immediately when you save
- Preview jobs automatically pause after 2 hours — redeploy preview to reset the window
Check job history:
- Open Admin → Background Jobs to see whether the job has run, when, and whether it succeeded or failed
- Open Server Logs to see live output from the most recent tick
If the job is running but failing:
- The error message appears in both Server Logs and the job history
- Vulcan retries failed jobs up to 3 times (60-second delay between attempts) before dropping them
- Common causes: an external API is down, an AI inference call is timing out, or there's an unhandled exception in the job logic
- Paste the error into chat: "My [job name] is failing with this error — how do I fix it?"
If the job ran but did nothing:
- The job logic probably has an early-exit condition (e.g. "skip if today's report already exists"). Check the Server Logs for a log line explaining why it skipped.
The AI stopped and said it needs direction
Symptoms: The AI's response ends with a message like "I've been unable to fix the build error after multiple attempts" or "I've been reading files without making changes — please give me more specific direction."
What happened: The AI hit a self-imposed limit to avoid going in circles. There are two reasons this happens:
- Build loop — two consecutive rounds where the AI ran a build check and it failed. The AI stopped rather than continuing to guess.
- Read loop — three consecutive rounds where the AI was reading files but not making any changes.
What to do:
- Read the last error carefully. The AI usually surfaces the exact file and line that's failing. Paraphrase what you want fixed: "The error says
cannot find module './utils'— create that file with the helper functions." - Give more specific direction. If the AI seems stuck on where to start, describe the approach: "Just change the button color for now, nothing else."
- Ask it to explain first. "Before making changes, explain what's causing this error and what you plan to do." Sometimes a reasoning step helps.
- Restore a version. If things have gotten messy across several failed rounds, roll back to a known-good state and start fresh with a more focused request.
Something else is broken
If you're hitting something not covered here:
- Describe the issue clearly in the chat — the AI can often diagnose and fix unexpected behavior
- Check if the issue appeared after a specific change (and restore a version if so)
- Reach out to the #eng_product_platform_team Slack channel for help