Find the failing surface
Troubleshooting
Most Vibecodr issues get easier once you name the surface that is failing: editor preview, public playback, embed delivery, search/discovery, or Pulse backend behavior.
Troubleshooting guide for Vibecodr user, project, runtime, and discovery issues.
Implementation focus
Use this page before changing code so you can identify whether the problem belongs to source shape, release artifact, player route, embed contract, public metadata, or backend capability use.
Expected outcomes
- Separate preview issues from published playback issues.
- Debug Pulse calls without moving trusted work into browser code.
- Report public-route problems with enough detail for support or agents to help.
- Recover safely when metadata, embeds, or discovery look stale.
When preview, publish, or playback looks wrong
Start by naming which surface is wrong: Studio preview, the public player, an embed, search/discovery, or a Pulse route. Those surfaces share a product model, but they do not all prove the same thing. A preview issue usually points at source or build shape. A player issue usually points at the published artifact or runtime launch contract.
For public problems, keep the report concrete. Include the route, project or post id when available, what you expected to happen, what actually happened, and whether the issue appears for signed-in owners, signed-out viewers, embeds, or agents.
- If preview fails, check entry files, imports, dependency assumptions, and browser console output.
- If publish succeeds but playback fails, compare the live player route with the latest cut.
- If an embed behaves differently, check whether it is live or pinned to an exact artifact.
- If discovery looks stale, check public metadata and allow time for crawlers and caches to refresh.
When backend behavior fails
Pulse issues are easier to debug when you separate route shape, request payload, capability use, and external provider behavior. Confirm the client is calling the intended /api route, the handler validates input, and the Pulse returns a safe app-facing error when work cannot complete.
Do not fix a backend problem by moving secrets into browser code. Use env.fetch, env.secrets, env.request, env.log, confirmed MCP tools, and owner-visible logs to keep the trusted work in the right place while giving users enough information to recover.
- Check the Pulse route and handler style before changing client code.
- Confirm required secrets or connected accounts are configured.
- Return stable errors the vibe can render without exposing sensitive details.
- Use Support when owner-visible logs and route checks do not explain the failure.
Task example and next paths
Example: a public app works in Studio but fails on the player page. Check whether the issue belongs to source preview, published artifact playback, embed mode, Pulse routing, or stale discovery metadata before changing code.
Use the related paths below as the next reading order. They are generated from the same route metadata that powers public HTML, markdown aliases, sitemap coverage, and docs navigation, so users and agents see one consistent documentation graph.
- Related path: /support/bug-report
- Related path: /docs/edit-manage
- Related path: /docs/calling-pulses
- Related path: /docs/embeds