Troubleshooting

The PulseDev button never appears

Work through these in order:

1. Is the project's server running? In the app, a project that isn't running says "The server isn't running" and offers no embed snippet. Start it from the toolbar.
2. Does the script load? Open the widget.js URL from your tag directly in the browser. If you get JavaScript back, the server is fine. If the page doesn't load, the port in your tag doesn't match the one the app shows for this project.
3. Is the tag on this page? View source or the Elements panel and look for widget.js. Dev-only checks can hide it if your dev server reports a production environment.
4. What does the console say? The widget logs lines that start with [PulseDev].

Each project gets its port the first time its server starts, somewhere from 3899 upwards, and keeps it after that. The 3899 in these docs is only an example. Copy the snippet from the project in the app rather than typing it.

"Can't reach PulseDev"

The widget loaded but lost the server, usually because the project was stopped or the app quit. Your notes are safe; they're stored on disk. Start the project again and the widget reconnects on its own. It retries every few seconds, or you can press Retry now.

Token rejected

The widget's settings show "That token was rejected. Copy it again from the PulseDev app." Every project has its own token, shown under Project token in the app with a Copy token button.

If your tag has a data-token attribute, it wins over a token you paste into the widget's settings. So when the tag carries an old token, fix the tag; pasting a new one in the widget won't stick after a reload. If you leave data-token off, the widget asks for the token once and remembers it in that browser.

Requests fail from a custom hostname

By default the server only accepts widget requests from pages on localhost, 127.0.0.1 or ::1, on any port. Sites served at something like myapp.test (Laravel Herd or Valet), a .local name, or a tunnel URL are blocked by CORS, and the browser console shows the error.

Turn on Allow any origin in Settings › General › Network. The token is still required for every request. The setting applies to servers started after the change, so stop and start the project.

Testing on a phone or another device

The server listens on loopback only. To reach it from another device on your network, turn on Allow network access in Settings › General › Network, restart the project, and point the tag at your Mac's local IP address instead of localhost. The page itself is then on a non-localhost origin too, so Allow any origin needs to be on as well.

The widget loads twice

If Set up project wrote a tag into index.html and you also added a snippet by hand, the widget script runs twice. The second copy fails to register and logs an error. Keep one. Set up project saved your original file as index.html.pulsedev.bak if you want to go back.

Vite won't start after Set up project

On Vite + React and Vite + Vue projects, Set up project adds @pulsedev/vite to your Vite config. That package isn't on npm yet, so the import fails. Restore the config from its .pulsedev.bak copy or delete the two added lines. Details on the Vite plugin page.

Agent not found

The run fails with "<agent> CLI not found. Install it or set its path in Settings › Agents."

• Open Settings › Agents and press Re-check. It lists each agent as Detected or Not found and shows where it looked.
• If the agent is installed in a folder PulseDev doesn't search, such as a Node version manager's directory, use Custom path… to point at the binary.
• If the agent is detected but the run still fails straight away, open Terminal and run it once. It is most likely waiting for you to sign in.
• OpenCode is temporarily disabled. Choose Claude Code, Codex or Gemini CLI instead.

Full setup steps are on Set up your coding agent.

The note ran with a different agent than I picked

On the free plan only the default agent runs, whatever the widget picker says. Change the default in Settings › Agents, or upgrade to Pro to pick per note. An agent switched off under In widget picker is also skipped in favour of the default.

"Element not found in this project"

The agent looked for the element's markup in the project folder and couldn't find it, so it stopped without editing anything. This usually means the tag on the page carries the token of a different project, for example after copying a snippet between repos. Use the snippet from the project whose source renders the page.

Approve fails or applies with errors

The note shows "Applied (with errors)" and a line like src/App.vue: old_string not found in file. Proposed changes are exact find-and-replace edits made against the file as it was when the agent read it. If you or a formatter changed that part of the file in the meantime, the edit no longer matches and is skipped. Other edits in the same note still apply.

Reply on the note to ask the agent to try again against the current file, or Reject and send a fresh note. Revert undoes the changes that were applied, as long as the files still contain them.

"Failed (exit N)"

The agent process exited with an error. Common causes are a session that has expired, a usage limit on your plan, or a model provider that isn't configured. Run the same agent in Terminal inside the project folder to see the full message.

Still stuck?

Email [email protected] with your macOS version, a screenshot of Settings › Agents, and any [PulseDev] lines from the browser console.