> For the complete documentation index, see [llms.txt](https://docs.goassay.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.goassay.ai/developers/use-tools-advanced/troubleshooting.md). # Troubleshooting Match local MCP refusals and server errors to their meaning and next action. Start with the profile your client uses: ```sh npx -y @goassay-ai/mcp status npx -y @goassay-ai/mcp doctor ``` For a named profile, add `--profile ` to both commands. Read the exact refusal before changing a limit. After an uncertain paid timeout, follow [Retries and idempotency](/developers/use-tools-advanced/retries-and-idempotency.md) before starting another purchase. ## Sign-in and keychain | Code / message | Meaning | Fix | | --------------------------------------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Only `assay_sign_in` is offered | This profile is signed out. | Follow [Install assay-mcp](/developers/use-tools-get-started/install-assay-mcp.md). | | Sign-in link returned after a connection ends | The server no longer accepts the stored sign-in. | Open the returned link or run `npx -y @goassay-ai/mcp login` for the same profile. The browser does not reopen automatically after a connection ends. | | **The sign-in was declined in the browser.** | Consent was declined. | Run login again if you intend to approve it. | | **The sign-in answer did not come from Assay; it was refused.** | The callback failed the issuer or response checks. | Start a fresh login; do not reuse or alter the callback URL. | | **The sign-in did not complete. Try again.** | The sign-in exchange failed. | Check connectivity and start login again. | | **The sign-in was not finished within 5 minutes. Try again.** | The approval wait expired. | Start login again and finish within the new window. | | **The sign-in was cancelled.** | The sign-in wait was aborted. | Start a new login when ready. | | **Could not open a local port for the sign-in.** | The local callback listener could not bind. | Allow the local callback listener and retry. | | **Assay sign-in is already in progress in another window.** | Another login is active for this profile. | Finish or cancel that login first. | | `-32001`: **Assay sign-in in progress in another window.** | Waiting for the profile lock timed out. | Let the other operation finish, then retry. Do not delete an active lock. | | **No OS keychain is available.** (start of message) | The OS store is unavailable; the MCP has no file fallback. | Enable macOS Keychain, Windows Credential Manager or Linux Secret Service. Ignore the SDK suggestion in the message. Machines without a keychain, such as CI runners and containers, are not supported yet; see [CLI reference](/developers/use-tools-advanced/cli-reference.md#environment-and-headless-use). | | **Unlock your keychain, then try again.** | The store is locked or access was refused. | Unlock it or review its access prompt, then retry. | | **Assay refused the API key in the environment.** | The `ASSAY_API_KEY` value was rejected. | Remove an unintended `ASSAY_API_KEY` and use the browser sign-in, or check that the key is still active. See [CLI reference](/developers/use-tools-advanced/cli-reference.md#environment-and-headless-use). | ## Payment setup and local permission | Message / code | Meaning | Fix | | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Paid calls through this server are off.** | This exact URL is not allowed for payments. | Use [URLs and profiles](/developers/use-tools-advanced/urls-and-profiles.md) to allow the correct path and query in a terminal. | | **This tool is paid, and paid calls are off for this agent.** | A key needs setup or an active wallet-approved permission. | Follow [How paying works](/developers/use-tools-get-started/how-paying-works.md), including the fingerprint check. | | **This computer has no payment key for this profile yet.** | `enable-paid` has no key to open an approval page for. | Make one paid attempt from the client first. | | **This profile is not signed in.** | `enable-paid` needs a signed-in profile. | Sign in to that profile first. | | **The payment key stored on this computer is unreadable.** | The stored secret is not a usable payment key. | Stop paid attempts and review keychain access. If you replace the profile by signing out, also cancel the old key's on-chain permission; see [Security model](/developers/use-tools-advanced/security-model.md). | | **Assay asked for a payment this app could not complete. Try again.** | An unexpected local payment-path failure prevented completion. | Run the two checks above. If an earlier authorization may have been sent, reconcile the call before retrying. | | `PAYMENT_VOUCHER_DELEGATE_INACTIVE` | The server rejected a payment authorization because key permission expired or was revoked. | Review the key status and renew only if intended. | | `PAYMENT_DEBT_OUTSTANDING` | An account debt blocks paid calls. The MCP adds a funding link. | Open the returned funding link and resolve it there; repeating the tool will not settle it. | ## Payment refusals Before signing, `assay-mcp` runs its payment checks. A failed check returns **Assay asked for a payment this app refused:** followed by a reason. Find that reason below. The code column is for bug reports; it is not in the message. | Reason in the message | Code | Fix | | ------------------------------------------------------------------------------------ | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | | the amount is above the local limit per call | `G7_PER_CALL` | Choose a cheaper call, or raise the local limit; see [Spending limits](/developers/use-tools-get-started/spending-limits.md). | | the amount would pass the local limit per 24 hours | `G7_PER_DAY` | Wait for older amounts to leave the rolling window, or raise the local limit. | | the amount is above the confirmation limit and was not confirmed | `G7_CONFIRMATION_REQUIRED` | Approve the exact payment in a client that supports confirmation prompts. | | the confirmation was for another payment | `G7_CONFIRMATION_MISMATCH` | Start a new attempt and approve only the payment shown. | | the amount is above the payment key's on-chain cap | `G6_DELEGATE_CAP` | Use a cheaper call, or raise the key's cap with `enable-paid` and your wallet. | | the amount is above the escrow's on-chain cap | `G6_ESCROW_CAP` | Use a cheaper call, or raise the account ceiling with your wallet. | | the provider is not in the allow-list | `G8_PROVIDER_NOT_ALLOWED` | Review the local provider list; see [Access policy](/developers/use-tools-advanced/access-policy.md). | | paid calls through this server are off | `G11_URL_NOT_PAID` | Allow this URL in a terminal; see [URLs and profiles](/developers/use-tools-advanced/urls-and-profiles.md). | | the amount is above the quoted price / there is no price quote for this tool | `G3_ABOVE_QUOTE` / `G3_NO_QUOTE` | Discover the tool and its price again. Do not approve an unexplained increase. | | the payment key's grant has expired / is not active | `G4_EXPIRED` / `G4_INACTIVE` | Renew the key with `enable-paid`, only if you intend to. | | the payer has not authorised this payment key | `G4_NOT_DELEGATED` | Finish [How paying works](/developers/use-tools-get-started/how-paying-works.md) for this key. | | the payment key's grant could not be read from the chain / the chain read is too old | `G4_NO_CHAIN_READ` / `G4_STALE_READ` | Restore connectivity and try again once the chain can be read. | | Any other reason | | Keep the exact text and do not change limits; it will not help. Contact Assay support with the message. | The tool result also carries `_meta["assay-mcp/refused"]` with `guard` (such as `G7`) and the same `reason` text. ## Network and protocol | Code / message | Meaning | Fix | | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `-32002`: **Assay did not answer in time.** | A forwarded exchange exceeded 120 seconds, including its body. | Check connectivity and retry with the saved idempotency key. | | `-32002`: **Assay is busy with other calls from this app. Try again.** | No forwarding slot became available; this request was not sent. | Reduce parallel calls, then retry. | | `-32003`: **Can't reach Assay (…)** | Network exchange failed. The reason can include a network error code or **blocked: not an Assay address**. | Restore network access or use the built-in Assay origin. Keep the same key for a retry. | | `-32003`: **could not renew the sign-in; try again** inside the message | Token renewal failed temporarily. | Restore connectivity and retry; use login if the connection has ended. | | `-32000`: **Assay sent no answer.** / **Assay's answer had no result for this request.** | No response matched the forwarded request. | Retry with the same key and report a recurring failure. | | `-32000`: **Assay's answer was too large.** | The response exceeded a local response-size bound. | Reduce the requested output if the tool supports it. A timeout-like failure does not establish that no payment occurred. | | `-32000`: **Assay refused the request (HTTP …)** | A non-success response had no matching MCP answer. A recognized reason may be appended. | Read the attached code. Suspended agents, suspended organizations and blocked accounts need account-owner review. | | `-32600`: **A request with this id is already in flight.** | The client reused an active JSON-RPC ID. | Give each exchange a unique request ID; keep the idempotency key for the logical operation. | | `-32700`, `-32600`, `-32601` | Invalid JSON, invalid MCP request, or unsupported method. | Correct the MCP client request or use a supported method. | ## Server errors Errors that Assay's server returns, such as `TOOL_NOT_ALLOWED`, `MCP_QUOTA_EXCEEDED` or `IDEMPOTENCY_IN_PROGRESS`, are listed in [MCP tools: shared errors](/developers/reference/mcp-tools.md#shared-errors-and-metadata). Raising local limits does not fix them. ## Check it worked Rerun `status` for the affected profile and repeat the appropriate free or paid call once the reported cause is resolved. A successful retry returns a result or a replay. If it remains refused, keep the exact message and relevant guard or server code with your diagnostic report.
Optional: startup, install and log-file failures | Message / area | Meaning | Fix | | ----------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | **changes local safety settings, so it runs only in an interactive terminal** | Input or output is piped. | Run the command yourself; see [CLI reference](/developers/use-tools-advanced/cli-reference.md). | | `NODE_TLS_REJECT_UNAUTHORIZED=0` refusal | Certificate verification is disabled. | Remove that setting from the server environment. | | Environment HTTP proxy refusal | Proxy variables are set without a profile opt-in. | Remove unintended variables or enable your own proxy through `settings set`; see [CLI reference](/developers/use-tools-advanced/cli-reference.md). | | `NODE_EXTRA_CA_CERTS` warning | Additional certificate authorities are trusted. | Remove the setting unless you added it yourself. | | Built-in deployments table invalid / no usable web address | This build lacks required deployment configuration. | Use a correctly configured release; do not replace built-in hosts with values from a server reply. | | Profile file, permissions or symlink error | Local state failed the private-file checks. | Restore ownership and private permissions without replacing it with project files. See [Security model](/developers/use-tools-advanced/security-model.md). | | Project scope refused / name too long / conflicting entry | Install input violates client or scope rules. | Follow [URLs and profiles](/developers/use-tools-advanced/urls-and-profiles.md); use a supported scope and short unique name. | | Config is not plain JSON / not valid TOML | The helper cannot safely parse the client config. | Edit it through the client or correct the syntax before rerunning. | | **refusing to pass … through cmd.exe** | Windows CLI path or argument includes unsupported characters. | Add the entry in the client's own settings. | | Log path, symlink or header error | The file is not an acceptable MCP log target. | Use an absolute `.log` path in an existing directory; see [CLI reference](/developers/use-tools-advanced/cli-reference.md). |
## Go further * [CLI reference](/developers/use-tools-advanced/cli-reference.md) * [Retries and idempotency](/developers/use-tools-advanced/retries-and-idempotency.md) ## Next You have reached the end of Use tools. Return to [Install assay-mcp](/developers/use-tools-get-started/install-assay-mcp.md) when setting up another client. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.goassay.ai/developers/use-tools-advanced/troubleshooting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.