Errors
Handle failures explicitly
The JavaScript page helpers are designed to fail safely for unavailable targets/actions and commonly resolve to null. Guard important results. The real Puppeteer bridge can also return structured automation errors such as invalid requests, unavailable bridge state, or a missing matching page.
const saveButton = await SOCIALBROWSER.page.click("#save"); if (!saveButton) { console.warn("Save button was not available"); return null; }| Condition | Recommended response |
|---|---|
| Endpoint does not answer | Confirm Social Browser is running and API/debugging access is enabled in API Clients. |
| No matching target | Refresh the live target list; do not reuse an old runtime ID. |
| Selector returns no element | Wait for the expected page state, use a stronger selector, and guard a null result. |
| Navigation replaces the renderer | Wait for navigation/page readiness and resolve the page again when necessary. |
| Puppeteer method unsupported | Use a supported helper/Electron path or another CDP method available in the installed build. |
Troubleshooting
Common setup problems
The connection is refused
Confirm Social Browser is running, open browser://local/settings/api-clients, and verify that developer/API access is enabled. Then use the exact endpoint shown by the installed build.
Puppeteer connects but I see the wrong page
A browser can expose several live targets. Enumerate pages and verify URL/title/Profile context. Never assume pages()[0] is your intended Profile.
My stored targetId stopped working
That is expected after lifecycle boundaries such as restart/reconnect. Runtime target IDs are not durable. Discover the target again.
A helper returns null
The target may not exist yet, may not be visible/enabled, or the action may not be available. Wait for the expected state and guard the return value.
A Puppeteer API is unavailable
The embedded browser supports the Puppeteer/CDP paths implemented by the current build, but not every CDP domain is guaranteed. Prefer the documented Social Browser helper or supported Electron path when a direct Puppeteer call is unavailable.
Reliability
Lifecycle and target-selection rules
Find the intended target immediately before use instead of caching a runtime target for a long time.
A restart/reconnect can create new runtime IDs even when the persistent Profile is the same.
Check URL/title/Profile context before sending an action in a multi-Profile session.
Navigation can rebuild a renderer/CDP frame. Your code should wait for the new page state instead of assuming the old frame remains valid.
async function findTargetPage(browser, expectedUrlPrefix) { const pages = await browser.pages(); const page = pages.find(p => p.url().startsWith(expectedUrlPrefix)); if (!page) throw new Error("Target is not available"); return page; } let page = await findTargetPage(browser, "https://example.com/"); await page.goto("https://example.com/dashboard"); // Resolve/validate again when your workflow crosses a restart or reconnect boundary. page = await findTargetPage(browser, "https://example.com/");Security
Developer access is powerful — scope it carefully
- Keep the debugging/API endpoint bound to
127.0.0.1unless you intentionally secure another network path. - Do not publish API keys, client secrets or remote debugging endpoints in source control.
- Treat trusted User Scripts as privileged code; review them before enabling them.
- Use Profile-level separation so automation for one account/workspace does not accidentally act in another.
- Do not expose internal runtime IDs as durable database identifiers.
- Use these capabilities only on systems, pages and accounts you are authorized to operate.