Troubleshooting

Most troubleshooting can be delegated to an agent. Include the symptom, the command that failed, the expected result, and permission to run diagnostics.

Basic Diagnosis

Diagnose my Webcmd setup. Run the doctor command, check whether the selected
browser runtime and daemon are available, and tell me exactly what needs fixing.

The agent will usually start with:

webcmd doctor -v
webcmd setup --status

Runtime or Browser Bridge Fails

Webcmd says the browser bridge is unavailable. Diagnose the daemon and selected
browser runtime, restart what is safe to restart, and verify the connection
before retrying my task.

After changing the local browser with webcmd setup --browser ..., restart the daemon and run webcmd doctor.

Browser Session Errors

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

Code	Meaning	Next step
`SESSION_REQUIRED`	A browser command needs a root Session selector.	Create a Session, then retry with `--session <id>` before `browser`.
`INVALID_SESSION_SELECTOR`	The selector is not a readable Webcmd Session ID.	Use the ID returned by `session create` or `session list`.
`SESSION_SELECTOR_POSITION`	`--session` appears after the command name.	Move it before `browser`: `webcmd --session <id> browser ...`.
`SESSION_NOT_FOUND`	The Session does not exist in the selected Profile.	Check `session list -f json` with the correct Profile or create a Session.
`INVALID_SESSION_LIMIT`	`session list --limit` is outside 1–100.	Retry with a value from 1 to 100.
`SESSION_BUSY`	Another command is using the same Session.	Wait for it 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 sign-in or another human action.	Finish in the browser, then run the returned verifier.
`SESSION_WINDOW_CONFLICT`	Browser-window ownership changed unexpectedly.	Inspect the Session, then close and recreate it if needed.
`SESSION_CAPACITY_EXCEEDED`	The runtime reached its concurrent Session limit.	Close idle Sessions or wait for one to finish.
`HOSTED_CONTRACT_MISMATCH`	The CLI and Cloud disagree about the Session protocol.	Upgrade to the version requested by the service and retry.

A Session Lost Its Window

Keep the immutable, Profile-scoped Session ID and inspect it before creating a replacement:

webcmd --profile work --session work-project-k7 browser tabs
webcmd --profile work session list -f json

If its window no longer exists, close the stale Session and create a new one.

Multiple Profiles Are Connected

Webcmd found multiple browser Profiles. List them, explain which account or
browser state each represents, and recommend one for this task. Do not change
the default until I confirm.

See Authentication and Profiles.

Authentication Is Required

Use my `work` Profile. If the page requires authentication, pause and hand the
browser to me. Never request credentials, cookies, recovery codes, or one-time
codes in chat. After I finish, verify the signed-in page before continuing.

The authentication handoff belongs to the Session that created it. Run the returned verification command verbatim before retrying the browser task.

A Page or Selector Changed

The Webcmd task can no longer find the expected content. Inspect the live page,
determine whether navigation or page structure changed, complete the task using
the current interface, and refresh useful site knowledge. Keep the task
read-only and report what changed.

Remembered site structure is only a starting point. The live page is the source of truth.

Browser Results Are Empty

Webcmd returned no rows, but I can see results in the browser. Check the selected
Profile, current URL, filters, pagination, and rendered page state. Do not change
saved settings or submit anything. Return the requested fields with source URLs.

Hosted Browser Is Unavailable

Diagnose my Webcmd Cloud browser connection. Check the active workspace,
configured Cloud credentials, Profile status, and service reachability. Do not
print or replace secrets without my approval.

webcmd setup now configures local browser mode only. Cloud credentials are provisioned separately.

Node Fails on Startup

Webcmd requires Node.js 20.6 or newer:

node --version

Upgrade Node.js, reinstall Webcmd, and retry.

Advanced Diagnostics

Variable	Purpose
`WEBCMD_PROFILE`	Browser Profile alias or context ID.
`WEBCMD_WINDOW`	Optional `foreground` or `background` browser override.
`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.

webcmd setup --browser chrome uses an installed Google Chrome and stores its Webcmd-managed Profiles under ~/.webcmd/chrome/profiles. Webcmd does not install Chrome automatically. Custom browser builds use their own Profile directory and do not modify managed Cloak Profiles.

Start

Agent Harnesses

Understand Webcmd

Build and Share

Use Cases

Reference and Support

Troubleshooting

Troubleshooting

Basic Diagnosis

Runtime or Browser Bridge Fails

Browser Session Errors

A Session Lost Its Window

Multiple Profiles Are Connected

Authentication Is Required

A Page or Selector Changed

Browser Results Are Empty

Hosted Browser Is Unavailable

Node Fails on Startup

Advanced Diagnostics

​Troubleshooting

​Basic Diagnosis

​Runtime or Browser Bridge Fails

​Browser Session Errors

​A Session Lost Its Window

​Multiple Profiles Are Connected

​Authentication Is Required

​A Page or Selector Changed

​Browser Results Are Empty

​Hosted Browser Is Unavailable

​Node Fails on Startup

​Advanced Diagnostics

Troubleshooting

Basic Diagnosis

Runtime or Browser Bridge Fails

Browser Session Errors

A Session Lost Its Window

Multiple Profiles Are Connected

Authentication Is Required

A Page or Selector Changed

Browser Results Are Empty

Hosted Browser Is Unavailable

Node Fails on Startup

Advanced Diagnostics