> ## Documentation Index
> Fetch the complete documentation index at: https://docs.walletsuite.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common failure modes for agents connected to the hosted WalletSuite platform, and how to fix them.

Use this page when your agent is connected to the hosted platform at `https://mcp.walletsuite.io` but something is not working as expected.

<Info>
  Every response carries a structured `WalletSuiteError` — `category`, `code`, `message`, plus a `requiredAction` on `flow` errors. Check `category` first; it tells the agent what class of action to take. See [Structured Errors](/core-concepts/structured-errors).
</Info>

## Authentication (401 / 403)

An `auth`-category error means the bearer is bad or the credential behind it is not entitled to what you asked for.

### Symptom: requests start failing after a few minutes

The short-lived token expired.

Fix:

* re-authorize with the agent's key to get a fresh token — see [Connect your agent](/ai-agents/token-exchange)
* refresh proactively before the token expires rather than waiting for the first 401

### Symptom: `UNAUTHORIZED` on the token exchange itself

The agent's key is missing, malformed, or revoked.

Check:

* your server authorizes with the agent's key, not the model
* the credential has not been revoked in the dashboard — revoking it cuts the agent off immediately

Fix:

* provision a fresh key and rotate it into your server's secret store — the raw key never reaches the model, a prompt, or a downstream MCP call

### Symptom: `FORBIDDEN` on an otherwise valid call

The token is valid but its authority does not cover the operation — the agent's tool profile or scopes don't include it. See [Execution Levels](/ai-agents/execution-levels).

## A tool is missing

### Symptom: a tool you expected is not in the MCP schema

A tool the agent cannot reach is never registered — that absence is the prompt-injection boundary, not a bug. A tool appears only if the agent's tool profile and granted scopes both allow it — see [Execution Levels](/ai-agents/execution-levels).

Check:

* the agent's [execution level](/ai-agents/execution-levels) is high enough — `read`, `prepare`, `execute`, or `governed`
* the agent's granted scopes cover the tool (e.g. signing tools require `wallets:sign`)
* the tool is within the agent's granted tool profile

Fix:

* raise the agent's tool profile or granted scopes server-side, then reconnect the agent — see [Connect your agent](/ai-agents/token-exchange)

## An operation is denied

### Symptom: a signing call comes back denied

A denial is a deterministic policy decision, not a transient failure. Through the hosted MCP endpoint it surfaces as a `flow` error whose `message` carries the decision reason and whose `requiredAction` names the next step. The same request denies again until the request or the policy changes — do not blindly retry.

Common reasons ([full list](/core-concepts/structured-errors#policy-denials)):

* `chain_not_entitled` — the intent's chain is outside the chains you're entitled to. Sign on an entitled chain, or have it added to your plan.
* `no_matching_rule` — the org allowlist is armed and no active rule admits this operation. Adjust the request to satisfy a rule, or have an admin add one.
* `unclassified_operation` — the operation could not be typed; deny-by-default rejects it. Use a supported operation type.

See [Policy Gates](/core-concepts/policy-gates) for the rule model. Quote the `policyDecisionId` from the response when raising a support ticket.

### Symptom: a `flow` error before any signing happens

A prerequisite is missing. The `requiredAction` in the response is the concrete next step.

Fix:

* execute the `requiredAction` first, then retry the original request

## Feature not available

### Symptom: a tool exists but calls return a not-available error

The capability is not enabled for your plan — a `not_available`-category error.

Fix:

* confirm whether the capability is on your plan
* fall back to the read and prepare surface when possible

## Still stuck?

If the problem persists, contact the WalletSuite team at [support@walletsuite.io](mailto:support@walletsuite.io).