Troubleshooting

Fix connection, comment and sync problems.

Bud doesn't start

Read the terminal error. Keep exactly one bud.config.ts or bud.config.js in the Vite root, with a default export and at least one route. If you set port, it must be free and different from your app's port.

A screen or button is missing

Bud shows a feature only once it's set up: no Tasks without a task store, no comments without a discussion store, no Agents or Start task without the factory. Run npx bud doctor in your project; it says what each missing piece needs.

A page is blank

The artboard names the problem. If Bud can't start a browser, run npx playwright install chromium or install Google Chrome. If the page fails to load, open it directly: Bud's headless browser has no cookies of its own, so pages behind authentication or with an untrusted certificate don't render. Bud doesn't bypass your app's policies.

Edits don't show up

If the page updates when opened directly but not on the canvas, your server probably skips transformIndexHtml. See Vite and custom servers. After a config change, use the URL printed by the restarted server.

Nothing updates live

The icon at the bottom of the navigation rail shows the live connection: connected, reconnecting or offline. Bud reconnects by itself, and after a restart it reloads everything open. Your browser keeps a copy of what it last saw, per project; clearing the site's data only removes that copy, and Bud reads it again.

I can't comment

Comments need a ready storage adapter. With the default Beads adapter, install bd 1.3.1 or newer and run bd init in the project.
Set user.name and user.email with git config.