Wield error codes and how to fix them
Every Wield error has a code, a message and a hint. Read the code first, then do what the hint says. Most errors come from the browser connection, the site or a safety rule, and each one has a fix you can make yourself. If the error is unclear, run npx -y wield-mcp doctor, which checks every link in the chain and prints a fix for each problem.
How to read an error
A failed run returns ok: false with an error object. The error holds a code, a message and sometimes a step. The result also carries a hint for the agent, and a login_url when a login is needed.
Two checks cover most cases. Run npx -y wield-mcp doctor in a terminal. Then ask your agent for status, which reports whether the executor is online, the registry state and which sites you are logged in to.
Connection errors
executor_offline. The browser or the Wield extension is not running. Open your browser. Wield runs only while the browser is open. A background window is enough.
tab_error. The extension could not run in the site's tab. This usually means the extension's files changed on disk and the browser still runs the old version. Open the extensions page in your browser, such as chrome://extensions, and click reload on the Wield card.
registry_unreachable. wield.run cannot be reached and the recipe is not cached. Retry when you are online.
recipe_unsigned. Wield refused a recipe whose signature did not check out. Nothing was sent to the site. Update with npx -y wield-mcp@latest init. If the error stays, report it, because it can mean that something between you and wield.run changed the recipe.
Site errors
login_required. You are not logged in to the site in this browser. Open the login_url from the result, log in yourself, then ask again. Wield never handles passwords.
site_challenge. The site's bot protection answered instead of returning data. Wield itself is working. Open the site in your browser, use it once, and solve any check the site shows you. Then ask again. The extension may bring the tab to the front and ask you to click or scroll once. Wield does not solve checks for you.
expect_failed. The site answered, but not in the shape the recipe expects. The site has usually changed. Retry once. If it fails again, ask for a repair with request_recipe.
limit_exceeded. Either per-site pacing stopped the run, or a recipe hit a hard limit of 40 requests or 5 MB per response. For some sites, pacing allows about 30 requests an hour across all your agents. The message says when to try again, and the popup shows the hour's counts per site.
timeout. The site was too slow. Retry once.
invalid_params. The params do not match the recipe's schema. Nothing was sent. Fix the params and retry.
recipe_invalid. The recipe id is unknown or the recipe is broken. Use find_recipe to get the current id.
Safety and policy errors
confirmation_denied. The Allow window was denied, closed, or left open for two minutes. Nothing was sent. Do not retry unless you ask for it again. Look for the Allow window in your browser when a write is requested.
policy_denied. Your organization's policy does not allow this site, or does not allow write recipes. Only an admin can change that. See teams.
origin_blocked. A request went to a host the recipe does not list, or to a site you did not allow. Nothing was sent. Do not retry.
cancelled. The run was cancelled.
Codes at a glance
| Code | Retry? |
|---|---|
executor_offline, tab_error, login_required, site_challenge | After you fix the cause |
expect_failed, timeout | Once |
limit_exceeded | After the wait the message gives |
confirmation_denied, origin_blocked, recipe_unsigned, policy_denied | No |
Where the logs are
~/.wield/logs/executor-YYYY-MM-DD.ndjsonrecords each request a recipe made, with method, host, path, status and time, plus each result.~/.wield/logs/mcp-YYYY-MM-DD.ndjsonrecords the requests wield-mcp made to wield.run.
Neither file holds bodies, query values, params or results. Use them to see what was contacted, not what was sent.
FAQ
Should my agent retry automatically?
Only when the table above says so. Retrying a denied write, an origin block or an unsigned recipe does not help, and retrying a bot check can make the site's answer worse.
Why does doctor pass but a run fails?
The site changed, or it challenged the request. Run npx -y wield-mcp check for one live sample, then read the executor log for the failing request's status.
Where is the full list of codes?
The MCP tools reference has the complete error table, with the hint each code gives the agent.