Fix: Bolt API Routes Returning 404 or Not Executing
Quick Answer
Bolt's WebContainer has limited server-side capabilities. For simple API routes, ensure they're in the correct directory: src/app/api/[route]/route.ts for Next.js. For complex server operations, deploy to Railway or Vercel instead.
Quick Fix Summary
| Issue | API routes not working |
| Fastest fix | Check route file location |
| Use this page if | API routes return 404 Not Found |
Symptoms
- !API routes return 404 Not Found
- !Server-side code doesn't execute
- !fetch('/api/data') returns HTML instead of JSON
- !API works in local development but not in Bolt
Step-by-Step Fix
Check route file location
For Next.js App Router, API routes must be at: src/app/api/[name]/route.ts (not .js, not page.ts). The file must export GET, POST, etc. functions.
Verify the route exports
The route file must export named functions: export async function GET(request: Request) { return Response.json({ data: 'hello' }) }. Default exports don't work for API routes.
Check WebContainer limitations
Bolt's WebContainer can't run server-side Node.js APIs that require native modules (file system writes, child processes). Use client-side alternatives or deploy to a real server.
Test with a simple route first
Create a minimal test: src/app/api/test/route.ts with export async function GET() { return Response.json({ ok: true }) }. If this works, the issue is in your specific route code.
Frequently Asked Questions
Limited. WebContainers can run Next.js API routes for simple operations (database queries, JSON responses). Complex server operations (file processing, WebSocket servers) need a real server like Railway.
For production API routes, yes. Export to GitHub and deploy to Vercel (free) or Railway. The Bolt preview is for prototyping, not production server-side operations.
Related
Weekly Signals
Get the next fix, switch, or warning before it hits your build.
Join builders getting the community signals, fix patterns, and tool shifts that matter before they show up everywhere else.
Follow the signals →