Troubleshooting: Browser

Fix common issues with the embedded browser panel.

Localhost App Won't Load

Symptom: you navigate to http://localhost:3000 in the browser panel but see a connection error or a blank page.

Fixes:

  • Make sure your dev server is actually running. Check the terminal — look for the startup message (for example, ready on http://localhost:3000 from Next.js, or Local: http://localhost:5173/ from Vite). If the server is not running, start it with your usual command (npm run dev, yarn dev, etc.).
  • Try 127.0.0.1 instead of localhost. Some systems resolve localhost differently than expected. Replace localhost with 127.0.0.1 in the URL bar — for example, http://127.0.0.1:3000.
  • Content-Security-Policy headers. If your app sets strict CSP headers that prevent embedding in a webview, the browser panel will refuse to display it. In development mode, you can relax these headers. For example, in Next.js you can remove or loosen the frame-ancestors directive in your next.config.js for local dev only.

Browser Panel Height Collapses

Symptom: the browser panel shrinks down to a thin strip and you cannot see your app.

Fix: drag the panel divider (the thin bar between the browser panel and the panel above or below it) to resize the browser. Click and drag it upward to give the browser more vertical space.

If you want the browser to take up as much space as possible, use fullscreen mode: press Cmd+Shift+F (or Ctrl+Shift+F on Windows/Linux) to expand the browser panel to fill the window. Press the same shortcut to return to the normal layout.

Video or Audio Not Playing

The embedded browser panel does not support all media codecs. Certain video formats or audio streams may fail to play inside the panel.

Fix: right-click anywhere in the browser panel and choose Open in External Browser. This opens the current URL in your system's default browser (Safari, Chrome, Firefox, etc.), which has full codec support. Use this for media-heavy pages, video players, or anything that requires browser plugins.

Page Shows Blank / White Screen

A blank white screen usually means the page loaded but something went wrong in the JavaScript before any content could be displayed.

Fix:

  1. Click the DevTools button in the browser panel toolbar (the wrench or </> icon).
  2. Open the Console tab.
  3. Look for red error messages.

The most common cause for local development is a CORS error — your frontend is making a request to a local API, and the API is rejecting it because the request comes from a webview origin rather than localhost. To fix this in development, configure your API server to allow all origins:

  • Express / Node: add app.use(cors()) with the cors package.
  • FastAPI: add CORSMiddleware with allow_origins=["*"] for dev.
  • Next.js API routes: add Access-Control-Allow-Origin: * to the response headers in your route handler.

Remember to restrict origins again before deploying to production.