Troubleshooting

Run the doctor

The fastest first step is the bundled diagnostic, which checks the bridge, the native host, the kill-switch file, and the telemetry snapshot:


sfdt doctor --extension
sfdt doctor --extension --json   # machine-readable
sfdt doctor --extension --port 8080


sfdt extension status            # which browsers have the host installed
sfdt extension status --json


sfdt extension stats             # top features by activation count
sfdt extension stats --json
sfdt extension stats --limit 10

Open DevTools on the Salesforce tab (Cmd/Ctrl+Opt/Alt+I → Console). The extension tags its messages with [SFUT]:

Symptom	Likely cause	Fix
Bridge feature says “Bridge not running”	`sfdt ui` isn’t running	Start `sfdt ui`, then Test connection in options
”Test connection” fails	Wrong or stale token	Re-copy `~/.sfdt/bridge-token`; rotate it if needed and re-pair
A feature is missing from the menu	It’s toggled off, or kill-switched	Check the options page; run `sfdt feature-flags list`
⚡ side button doesn’t appear	You’re not on a Salesforce page, or it’s inside a VF iframe	The button mounts only in the top frame of Salesforce pages
Native messaging not used	Host not installed for this browser	`sfdt extension install-host --extension-id <id>`; verify with `sfdt extension status`
Major protocol mismatch warning	Extension and CLI versions diverged	Update both to the latest; see Bridge

Still stuck? Open an issue with the area: extension label at github.com/scoobydrew83/sfdt/issues .