Troubleshooting AI tool setups
The server does not appear, or no Gala tools are listed
| Symptom | Cause | Fix |
|---|---|---|
| The client shows the server as failed or never started | The command could not run: Node.js older than 20, no network for npx, or a typo in the command. | Run the command from a terminal (npx -y @gala-chain/gala-mcp-server@next). A working server waits silently on stdin; press Ctrl+C. Fix what it prints. |
| The server starts and exits at once with a message on stderr | A configuration mistake: an unknown toolset name, an empty --toolsets, composite in a selection, an ENVIRONMENT that is not prod or stage, or a malformed PRIVATE_KEY. | Read the message, it names the valid values. Correct the variable and restart the client. |
| Install fails to resolve the version | A range such as ^1.0.0 matches no prerelease. | Use the @next tag or the exact version. |
| The server is connected but a tool is missing | Its toolset is not selected, for example a Launchpad tool with GALA_TOOLSETS=core,gswap. | Add the toolset to GALA_TOOLSETS or --toolsets and restart the client. |
| The server was changed but the client behaves as before | The client keeps the process it started. | Restart the client, or disable and enable the server in its MCP settings. |
Tools answer with an error
| Symptom | Cause | Fix |
|---|---|---|
| A write says a wallet is required | The server has no PRIVATE_KEY: it is read-only. | Configure PRIVATE_KEY in the server's environment and restart (see security and keys). |
Every tool reports a configuration problem about WALLET_ADDRESS | The identity override is not the address of the key. | Unset WALLET_ADDRESS, or set it to the key's address, and restart. |
An address is refused for eth|0x... | The address was written with 0x after eth|. | Write eth|<checksummed 40 hex digits> or the bare 0x<40 hex>. |
| Data of the wrong network | The server is on prod, the default, and you meant stage. | Check with gala_launchpad_get_environment; set ENVIRONMENT=stage and restart, or call gala_launchpad_switch_environment. |
| Bridge or wrap tools name a missing package | A Solana package of the bridge is not installed. | Reinstall the server with its dependencies (npx does this itself). |
| Documentation tools find nothing | The docs site is unreachable and no cached index exists. | Set GALA_DOCS_BASE_URL to a reachable site, or set GALA_DOCS_OFFLINE=1 to use the index bundled with the server. |
The plugin
| Symptom | Cause | Fix |
|---|---|---|
| Each tool appears twice | The server was added with claude mcp add and the plugin starts one too. | Keep one: claude mcp remove gala, or uninstall the plugin. |
/omni-tool:setup says the server is not connected | The plugin's server did not start, or Claude Code was not restarted after the install. | Restart Claude Code, then run /mcp to see the server's state; apply the fixes of the first table. |
| The assistant says it cannot sign | The plugin starts the server without a key, on prod. | This is the default. Add a key only as described in security and keys. |
| Tool counts or topics differ from what the plugin says | The plugin documents the server from the day it was published; npx fetches a newer server. | Trust the live tool list and gala_launchpad_explain_sdk_usage. |
Still stuck
Ask the server's own documentation, which works offline:
gala_launchpad_search_gala_docs({
query: 'tool not found toolsets'
})
The per-package agent guides carry the failure tables of each SDK. This package's is the agent guide.