Skip to main content
Use this page when WalletSuite MCP is installed but something is not working as expected.

​
Authentication errors

See Credentials & Authentication for the header contract, tier rules, and full error taxonomy.

​
Symptom: Authentication is required

This usually means WALLETSUITE_API_KEY is missing. Check:
  • the MCP host config file
  • environment variable spelling
  • whether the config was reloaded after editing
Fix:
  • add a valid WALLETSUITE_API_KEY
  • restart or reload the MCP host

​
Symptom: requests fail even though the server starts

This often means the API key is present but invalid for the current environment. Fix:
  • verify the key in WalletSuite
  • replace the key and reload the host

​
Missing tools

​
Symptom: only read tools are visible

This is normal if you did not set MCP_BANDS. Fix:
  • use MCP_BANDS=read,prepare if you need transaction preparation tools
  • add sign and broadcast only when you also plan to enable OWS

​
Symptom: signing tools are missing

Check:
  • OWS_ENABLED=true
  • MCP_BANDS includes sign

​
Symptom: send_transaction is missing

Check:
  • OWS_ENABLED=true
  • MCP_BANDS includes broadcast

​
OWS issues

​
Symptom: OWS_LOAD_FAILED or Failed to load @open-wallet-standard/core

The local OWS binary is not available for your platform. Fix:
  • verify the host is using a supported macOS or Linux build
  • reinstall dependencies if needed

​
Symptom: OWS_WALLET_EXISTS

The requested wallet name already exists in the local vault. Fix:
  • choose a different walletName, or
  • use the existing wallet instead of creating a new one

​
Symptom: OWS_WALLET_NOT_FOUND

OWS could not find the named wallet. Fix:
  • verify walletName
  • verify OWS_VAULT_PATH if you are using a non-default vault location
  • create the wallet first in owner mode if it does not exist yet

​
Symptom: OWS_ACCOUNT_NOT_FOUND

The wallet exists, but it does not expose an account for the selected OWS chain. Fix:
  • verify the requested chain
  • use a wallet with support for that chain

​
Symptom: OWS_CREDENTIAL_INVALID

The configured passphrase or token does not match the local vault. Fix:
  • verify OWS_PASSPHRASE in owner mode
  • verify OWS_AGENT_TOKEN in agent mode
  • restart the server after making changes

​
Symptom: OWS_AGENT_TOKEN_EXPIRED

The token must be regenerated by the owner bootstrap flow. Fix:
  1. generate a fresh token
  2. update OWS_AGENT_TOKEN
  3. restart the server

​
Symptom: OWS_AGENT_TOKEN_INVALID

OWS could not find the configured agent token. Fix:
  1. generate a new token from the owner bootstrap flow
  2. update OWS_AGENT_TOKEN
  3. restart the server

​
Symptom: OWS_POLICY_DENIED

OWS policy rejected the signing request. Fix:
  • retry with an allowed chain
  • use a token whose policy allows the required operation

​
Symptom: OWS_INVALID_UNSIGNED_TX

The transaction input is not valid raw unsigned transaction hex. Fix:
  • pass raw unsigned transaction hex only
  • do not pass JSON objects

​
Symptom: OWS_RPC_URL_REQUIRED

You called send_transaction without the matching chain RPC URL. Fix:
  • set OWS_ETHEREUM_RPC_URL for ethereum
  • set OWS_TRON_RPC_URL for tron

​
Symptom: OWS_OWNER_MODE_REQUIRED

You tried to perform an owner-only operation while running in agent mode. Fix:
  • restart with OWS_AUTH_MODE=owner
  • set OWS_PASSPHRASE

​
Symptom: OWS_OPERATION_FAILED

OWS returned a generic failure that did not map to a more specific code. Fix:
  • check the server logs
  • verify vault path, credentials, and input data
  • retry with the simplest working owner-mode flow first

​
HTTP connection issues

​
Symptom: the client cannot connect to the HTTP server

Check:
  • that the server is running
  • http://localhost:3000/health
  • the full MCP path http://localhost:3000/mcp

​
Symptom: port already in use

Another local process is already using the selected port. Fix:
  • stop the conflicting process, or
  • choose another port, for example PORT=3001

​
Symptom: confusion between stateless and stateful mode

Most users should stay with MCP_HTTP_MODE=stateless. Only switch to stateful if you specifically need session-oriented behavior.

​
Host config issues

​
Symptom: the MCP host ignores the config

This often means the file location or top-level JSON shape is wrong for the host. Fix:
  • use the host-specific page in Install Guides
  • validate the JSON
  • reload the host

​
Symptom: the host still uses old settings

Fix:
  • restart the application, or
  • reload MCP servers from the host UI or CLI if the host supports it

​
Feature availability issues

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

Some backend features are feature-gated. Fix:
  • confirm whether the capability is enabled for your plan
  • fall back to the currently available read and prepare surface when possible

​
Still stuck?

If the server starts but behavior is still off:
  1. reduce the config back to the simplest working shape
  2. keep MCP_BANDS=read
  3. disable OWS
  4. verify one read-only prompt first
  5. add HTTP, prepare, or OWS only after the base setup works
If the problem persists, contact the WalletSuite team at support@walletsuite.io — include your MCP host, band config, a recent stderr snippet, and the chain you were hitting.