Step-by-step guides for the most common Bolt problems, written by real developers.
Payment processing fails even though credentials look correct. Users can't complete purchases. Stripe API returns errors.
Sometimes charge attempts fail silently or return cryptic error messages.
API requests timeout while waiting for response. Frontend gets 'fetch timeout' error or 504 error.
The endpoint works but is slow. Same endpoint sometimes works, sometimes doesn't.
API requests fail with CORS error: 'Access-Control-Allow-Origin header missing'. The browser blocks requests to a different domain.
Your frontend is on one domain and API on another, or localhost vs deployed URL.
Your API route returns a 500 Internal Server Error even though the code looks correct. The same logic works fine when tested manually.
Frontend gets error when calling the route, but no detailed error message.
WebSocket connections fail to establish. Real-time features don't work. Users don't receive live updates.
Connection hangs or connects then disconnects immediately.
GraphQL queries with deep nesting cause timeouts or excessive server load. User can request deeply nested data causing exponential database queries.
Server becomes unresponsive to legitimate queries.
API returns 429 Too Many Requests errors. Your app is making requests too quickly and hitting the rate limit.
Works initially then fails after rapid user actions.
POST or other non-simple requests fail because the CORS preflight OPTIONS request times out. Browser doesn't even send the actual request.
Requests work in some browsers but not others, or fail intermittently.
You've registered a webhook URL but never receive requests from the service (Stripe, GitHub, etc.). The webhook endpoint is never called.
The service shows 'failed delivery' or 'pending' status.
Users get errors when uploading files larger than limit. Upload fails even though file size seems reasonable.
Errors: 'payload too large', '413', or upload hangs indefinitely.
Emails aren't being sent. Email API returns success but users never receive the emails. Emails sent but marked as spam.
No error logs showing what went wrong.
Long-running operations (file processing, email sending, bulk updates) timeout. Tasks don't complete.
Operations that take >30 seconds fail on serverless deployments.
Users log in successfully but get logged out whenever they refresh the page or return later. The session persists during the same browser tab but is lost on navigation or reload.
This happens because authentication state isn't being saved to browser storage or the session storage isn't being retrieved on app initialization.
Your protected routes are either accessible without authentication or they continuously redirect authenticated users to login. Protected pages don't check auth status before rendering.
Users see blank pages, infinite redirect loops, or pages load with unauthenticated state briefly before hiding content.
Your OAuth2 provider (Google, GitHub, Facebook) authentication fails immediately with cryptic errors. The login redirect works but authorization fails.
Common signs: blank page on OAuth callback, 'client_id not found' in browser console, or authentication loops indefinitely.
API requests fail with JWT verification errors even though the token appears valid. Tokens work initially but fail after some time or across different server instances.
Symptoms include immediate '401 Unauthorized' on API calls, 'JsonWebTokenError: invalid signature', or tokens expiring immediately after issue.
Application gets stuck in redirect loop. User is continuously redirected between login and dashboard, browser shows error about too many redirects.
Page loads then immediately redirects, causing infinite loop.
Requests to Supabase hang indefinitely or timeout after 30 seconds. Login, signup, or database queries never complete.
The app connects fine locally but fails on deployment, or works initially then starts timing out under load.
API requests start failing with 'too many connections' or 'connect ECONNREFUSED' errors. The database was working fine but suddenly stops accepting connections.
This typically happens under load or after the app has been running for a while, and restarting the app temporarily fixes it.
Running `prisma migrate dev` fails with schema validation errors. The app can't sync with the database schema or migrations won't apply.
You see errors about 'Migration already applied', schema divergence, or the database being in a bad state preventing any migrations.
Firebase authentication never initializes. Login and signup endpoints return errors. The Firebase console shows requests aren't being received.
Common signs: 'Firebase app not initialized', 'auth/invalid-api-key', or auth always returns null.
Database queries timeout or take too long (>5 seconds). Complex queries with joins or aggregations are slow.
API endpoints that query database time out or users see loading spinners for too long.
Database connections accumulate over time. Pool reaches max connections and new queries fail. Eventually app becomes completely unresponsive.
Connection count grows with each request and never decreases.
Users see old data from Redis cache even after updates. Cache doesn't invalidate when data changes.
Data appears correct in database but cached version is stale.
npm install fails or warns about version conflicts. Packages require different versions of the same dependency.
Error: 'peer dep missing' or 'conflicting peer deps'
Your build fails because of ESLint warnings/errors. Code is correct but linter complains and build exits.
Works locally with warnings but deployment fails on lint.
Deployment build fails with 'killed' status or 'out of memory' error. The build process gets terminated by the system before completing.
This happens when building large applications with many dependencies or heavy bundling requirements.
Environment variables are undefined in your deployed application even though they're set in the platform. API keys, database URLs, and other config values come back as undefined.
Variables work fine locally but disappear after deployment.
Your app works perfectly in development but shows a blank white page after deploying to Vercel or Netlify. No errors in the browser console, just whitespace.
The deployment log shows 'Build succeeded' but the page won't render anything.
Netlify build fails due to plugin configuration errors. The deploy log shows 'Plugin error' but the app builds fine locally.
Specific plugin (Node version manager, environment variable handler, etc.) fails during the build process.
API routes that work fine locally timeout on Vercel. Long-running tasks like file processing, bulk database operations, or external API calls exceed the timeout limit.
Requests return 504 Gateway Timeout and logs show the function was killed.
TypeScript reports type errors that prevent build. Type checking fails even though code appears correct.
Build exits with 'TypeScript error found' message.
Your Bolt WebContainer takes a long time to start - 30+ seconds before seeing the dev server running. Development workflow is slow due to startup delays.
This happens consistently, making every new session wait.
Your Bolt app takes minutes to build even with small changes. Development speed suffers with slow hot reload and rebuild times.
npm run dev or npm run build takes excessive time (over 30 seconds for simple changes).
Fonts load slowly causing text to flash or shift layout (Cumulative Layout Shift). Users see unstyled text briefly before custom font loads.
This impacts Core Web Vitals and user experience.
Your JavaScript bundle is very large (over 500KB), making the app slow to load. First Contentful Paint takes several seconds even on good connections.
Users on slow networks experience long loading times.
Your app gradually uses more memory the longer it runs. DevTools shows increasing memory usage even after navigating away from components.
The app slows down over time or crashes after extended use.
Your app feels sluggish when interacting. Typing in inputs lags, clicking buttons is unresponsive. React is re-rendering too much.
Frame rate drops during interactions or when state updates happen.
You add onClick, onChange, or other event handlers to elements but they never fire. The function is defined but not being called when the event occurs.
Sometimes works in one component but not another. No console errors.
Using next/image causes errors. Image won't load or throws configuration error. Image optimization fails.
Error about missing width/height, or optimization service unavailable.
Modal dialogs aren't accessible. Users can tab to elements behind the modal, keyboard focus isn't trapped, or screen readers don't announce the modal.
Accessibility testing tools flag issues with focus management and ARIA attributes.
Form validation isn't working. Invalid data submits, or error messages don't display. Users don't know what's wrong with their input.
Validation logic exists but errors aren't shown to user.
Next.js throws a hydration mismatch error. The HTML from server doesn't match what React renders on client. Content flickers or changes when page loads.
Error: 'Warning: Did not expect server HTML to contain a
Tailwind CSS classes aren't being applied to elements. You add classes like 'bg-blue-500' but the element stays unstyled.
Sometimes works in some components but not others. Manual styles work fine.
A React component is not rendering anything to the page. The component exists, is imported, but produces blank space where content should be.
Parent components render fine, but this specific component shows nothing. No errors in console.
Users fill out a form and click submit, but nothing happens. The form doesn't send data to the backend. No errors displayed.
Sometimes the page refreshes but data isn't saved.
Images aren't showing on the page. You see the broken image icon or blank space where images should be.
The image tag exists in HTML but the source isn't loading.
You update React state with setState() or useState hook, but the component doesn't re-render. The state seems to update in DevTools but the UI doesn't change.
This happens with objects and arrays particularly.
You don't need to be technical. Just describe what's wrong and a verified developer will handle the rest.
Get Help