Troubleshooting

Most troubleshooting should be done by an agent. Give the symptom, the command, the expected output, and permission to diagnose.

Basic Diagnosis

Diagnose my Webcmd setup. Run the doctor command, check whether the browser runtime is available, and tell me what I need to fix.

The agent will usually start with:

webcmd doctor -v

Hosted Mode Is Unavailable

Diagnose my Webcmd Cloud connection. Check whether hosted mode is selected, whether the saved API key is available, and whether the Cloud service can be reached. Do not print or replace the key unless I approve it.

For switching modes, see Local or Cloud.

Runtime or Browser Bridge Fails

Webcmd says the browser bridge is unavailable. Diagnose the daemon and runtime, restart what is safe to restart, and explain whether public adapters still work.

Public adapters may still work. Authenticated, intercepted, UI, and browser-backed workflows need the bridge.

Browser Session Errors

Webcmd returned a SESSION_* error. Explain which Profile/Session is involved, whether another command or human handoff is holding it, and give me the next safe command.

Common Session codes:

Code	Meaning	Next step
`SESSION_REQUIRED`	A raw browser command needs a root Session selector.	Run `webcmd session create -f json`, then retry as `webcmd --session <session-id> browser ...`.
`INVALID_SESSION_SELECTOR`	The selector is not an opaque Webcmd Session ID.	Use an ID returned by `webcmd session create` or `webcmd session list`.
`SESSION_SELECTOR_POSITION`	`--session` was placed after the command name.	Move it before the command: `webcmd --session <session-id> browser ...`.
`SESSION_NOT_FOUND`	The selected Session is missing for the current Profile.	Run `webcmd session list -f json`; create a new Session if needed.
`INVALID_SESSION_LIMIT`	`session list --limit` is outside 1-100.	Retry with a limit from 1 to 100.
`SESSION_BUSY`	Another command is writing in the same Session or site scope.	Wait for the holder to finish; if it is dead, use `webcmd session close <session-id> --force` as the last resort.
`SESSION_PAUSED_FOR_HUMAN_HANDOFF`	The Session is waiting for user action such as sign-in.	Finish the action in the browser, then run the returned verifier before retrying.
`SESSION_WINDOW_CONFLICT`	The Session’s window ownership no longer matches Webcmd’s expected window.	Inspect with `webcmd session list`; close and recreate the Session if needed.
`SESSION_CAPACITY_EXCEEDED`	The account or runtime has reached its concurrent Session limit.	Close idle Sessions or wait for one to finish.
`HOSTED_CONTRACT_MISMATCH`	The hosted CLI and cloud API disagree about the Session protocol.	Upgrade `webcmd` to the version pinned by the cloud service, then retry.

Multiple Profiles Are Connected

Webcmd found multiple browser profiles. List them, recommend which one to use for this task, and set the default only after I confirm.

Profiles matter when commands depend on login state. See Authentication and Profiles for profile and sign-in help.

Authenticated Commands Return Empty Results

`webcmd acme invoices` returns empty rows, but I can see invoices in the browser. Check whether this is a login/profile issue or an adapter issue. Preserve the output schema.

The agent may ask you to sign in once. It should not store credentials in code. See Authentication and Profiles for the sign-in flow.

original command -> AUTH_REQUIRED -> webcmd <site> login -> user signs in -> webcmd <site> whoami -> retry original command

Adapter Returns Wrong or Empty Data

Heal this Webcmd adapter. Command: `webcmd example jobs "designer"`. Expected columns: title, company, location, salary_text, posted_at, url. It now returns empty rows. Repair it and verify the result.

The agent should repair the existing adapter rather than create a duplicate command.

Output Shape Changed

The command still runs, but the JSON shape changed. Restore backward compatibility for existing fields and add any new fields as optional keys.

Stable output is more important than exposing every new site field.

Plugin Problems

Webcmd core ships without site adapters. If a site is missing, search and install it explicitly before diagnosing command code:

webcmd plugin search <site> -f json
webcmd plugin install <installSource-from-search>

This Webcmd plugin is installed but its commands do not appear in `webcmd list -f json`. Diagnose the plugin manifest, adapter paths, and install state.

External CLI Problems

`webcmd releasectl status` fails, but `releasectl status` works directly. Check the Webcmd external CLI registration and fix the binary or PATH configuration.

Node Fails on Startup

Check my Node version and Webcmd installation. If Node is too old, tell me the exact upgrade needed before changing anything.

Webcmd requires Node.js 20 or newer:

node --version

Upgrade Node.js, reinstall Webcmd, then retry.

Advanced Diagnostics

Useful environment variables:

Variable	Purpose
`WEBCMD_PROFILE`	Browser profile alias or context ID.
`WEBCMD_WINDOW`	Optional `foreground` or `background` override; browser commands default to `background`.
`WEBCMD_BROWSER_CONNECT_TIMEOUT`	Seconds to wait for the browser bridge.
`WEBCMD_BROWSER_COMMAND_TIMEOUT`	Seconds to wait for one browser command.
`WEBCMD_CDP_ENDPOINT`	Manual CDP endpoint for remote browsers or Electron apps.
`WEBCMD_CDP_TARGET`	Filter CDP targets by URL substring.
`WEBCMD_CACHE_DIR`	Browser state and network cache directory.
`WEBCMD_VERBOSE`	Enable verbose logs.

Start

Agent Harnesses

Understand Webcmd

Build and Share

Use Cases

Reference and Support

Troubleshooting

Troubleshooting

Basic Diagnosis

Hosted Mode Is Unavailable

Runtime or Browser Bridge Fails

Browser Session Errors

Multiple Profiles Are Connected

Authenticated Commands Return Empty Results

Adapter Returns Wrong or Empty Data

Output Shape Changed

Plugin Problems

External CLI Problems

Node Fails on Startup

Advanced Diagnostics

​Troubleshooting

​Basic Diagnosis

​Hosted Mode Is Unavailable

​Runtime or Browser Bridge Fails

​Browser Session Errors

​Multiple Profiles Are Connected

​Authenticated Commands Return Empty Results

​Sign In and Retry an Authenticated Command

​Adapter Returns Wrong or Empty Data

​Output Shape Changed

​Plugin Problems

​External CLI Problems

​Node Fails on Startup

​Advanced Diagnostics

Troubleshooting

Basic Diagnosis

Hosted Mode Is Unavailable

Runtime or Browser Bridge Fails

Browser Session Errors

Multiple Profiles Are Connected

Authenticated Commands Return Empty Results

Sign In and Retry an Authenticated Command

Adapter Returns Wrong or Empty Data

Output Shape Changed

Plugin Problems

External CLI Problems

Node Fails on Startup

Advanced Diagnostics