Troubleshooting

Start with:

npx -y wield-mcp doctor

It checks every link in order (Node, the bridge, each browser's registration, the extension's connection and version, recipes, signatures, your account, your AI apps) and prints a fix for each problem. npx -y wield-mcp check then runs one live sample.

#"The extension is not connected" / executor_offline

Windows: the bridge is registered under HKCU\Software\<browser>\NativeMessagingHosts\run.wield.bridge. doctor reads those keys.

#tab_error: "reload the Wield extension"

The extension's files on disk changed and the browser still runs the old version. Open chrome://extensions (or vivaldi://, edge:// …) and click the reload arrow on the Wield card. doctor flags this when the browser runs an older build than the one on disk.

#login_required

You're not logged in to the site in this browser. Log in yourself (the agent gets the login link), then ask again. Wield never handles passwords.

#site_challenge

The site's bot protection answered instead of the data. Wield itself is working.

1. Open the site in your browser and use it once: search for something, solve a check if one appears.
2. Ask again.

The extension retries once by itself, and may bring the tab to the front and ask you to click or scroll once. Some sites (e.g. bahn.de) only trust a browser after some normal use.

#limit_exceeded

Either:

• Wield's per-site pacing stopped the run: some sites allow about 30 requests an hour in total across all your agents. The message says when to try again. The popup shows this hour's counts per site.
• Or a recipe hit a hard limit: 40 requests, 5 MB response.

#expect_failed

The site answered, but not the way the recipe expects; usually the site changed. Wield retries read recipes once with the last version that worked. If it keeps failing, tell us with request_recipe; health checks flag broken recipes for repair too.

#confirmation_denied

The Allow window was denied, closed, or left for two minutes. Nothing was sent. Look for the window in your browser when you ask for a booking or a message.

#recipe_unsigned

Wield refused a recipe whose signature didn't check out, and nothing was sent. If it happens for a public recipe, update: npx -y wield-mcp@latest init. If it persists, report it: it can mean something between you and wield.run changed the recipe.

#policy_denied

Your organization's policy doesn't allow this site, or doesn't allow write recipes. Only an admin can change it (teams).

#The AI app doesn't show Wield's tools

• Claude Desktop: it rewrites its config while running. Quit it fully, run init from a terminal, then reopen. With the bundle, check Settings → Extensions.
• Claude Code: claude mcp get wield should list it. Start a new session after adding.
• Cursor: Settings → MCP shows the server and its state. Toggle it after editing ~/.cursor/mcp.json.
• All apps: they start servers with a minimal PATH, so npx may not be found. Use the absolute paths init prints.

#Slow runs

The first run on a site opens a background tab (1–4 s). Later runs reuse it, and find_recipe opens it ahead of time. npx -y wield-mcp speed measures what your agent waits for; the median across our read recipes is under a second.

#Logs

• ~/.wield/logs/executor-YYYY-MM-DD.ndjson: every request recipes made (method, host, path, status, time) and every result.
• ~/.wield/logs/mcp-YYYY-MM-DD.ndjson: every request wield-mcp made to wield.run.

Neither contains bodies, query values, params or results.