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

# Troubleshooting

> Common issues with the Yellow.pro MCP server — connection, authentication, permissions, and error behaviour.

## Client shows no tools / server fails to connect

**1. Register through the CLI**

Use `yellow-pro setup claude-code` (or `claude mcp add` directly) rather than editing config files by hand. Claude Code reads MCP config from `~/.claude.json`, not `~/.claude/settings.json`.

**2. Check the PATH**

The client spawns the server without loading your shell profile, so `yellow-pro-mcp` must be on the client's `PATH`. Check with `which yellow-pro-mcp`. If the installer printed a PATH hint, add that directory to your profile and restart the client.

**3. Restart the client**

Servers connect at session start, so restart the client after changing any MCP config.

**4. Verify the server starts**

Confirm the server itself runs:

```bash theme={null}
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | yellow-pro-mcp
```

A healthy response contains a `serverInfo` block and exits cleanly.

## Some tools are missing

Check `YELLOW_PRO_MODULES` character by character. Unrecognised names are silently dropped with no warning, so a plural typo like `markets,account` leaves you with account-only tools. The only accepted tokens are `market`, `account`, and `trading`.

If trading tools specifically are absent, `YELLOW_PRO_ENABLE_TRADING` is not set to `true`.

## Authentication errors

**`invalid_api_key`**

Private tools need all three of `YELLOW_PRO_API_KEY`, `YELLOW_PRO_API_SECRET`, and `YELLOW_PRO_APP_SESSION_ID`, and they must match the environment you are hitting. Staging keys do not work on production, and vice versa.

If you registered with `yellow-pro setup hermes`, the credentials were almost certainly not written — see the [hermes caveat](https://docs.yellow.pro/mcp/installation.md#setup-helpers).

**`invalid_timestamp`**

Your machine clock is more than a few seconds off the exchange's. Sync it:

> [tab] macOS
>
> ```bash theme={null}
> sudo sntp -sS time.apple.com
> ```

> [tab] Linux
>
> Use `chrony` or `ntp` to synchronize the system clock.

**Permission / `403` errors on a tool that otherwise works**

The API key is missing a scope. Check it against the [scope table](https://docs.yellow.pro/mcp/credentials.md#scopes-and-tools) — reads and trades are separate scopes, and spot and futures are separate again.

## Trading commands fail with "trading is disabled"

Set `YELLOW_PRO_ENABLE_TRADING=true` in the MCP client's env config. This is intentional.

> [!WARNING]
>
> Do not work around this by calling the REST API directly. The flag exists so that order placement is a deliberate action. Read [Risk and safety](https://docs.yellow.pro/mcp/risk-and-safety.md) first.

## Empty results instead of data

Almost always a timestamp unit mismatch. The three formats in use — milliseconds, Unix seconds, and RFC3339 — vary per tool, and the wrong one returns an empty set rather than an error. See the [timestamp table](https://docs.yellow.pro/mcp/tools.md#timestamp-units-differ-per-tool).

## Error behaviour worth knowing

> [accordion] 429 responses fail immediately
>
> Rate-limit responses are thrown straight away — there is no retry and no backoff. Lowering `YELLOW_PRO_RATE_LIMIT_MS` therefore converts throttling into hard failures rather than slower requests. The default is 100 ms.

> [accordion] Requests time out at 30 seconds
>
> There is no configurable timeout.

> [accordion] Error-shaped HTTP 200 responses become thrown errors
>
> The exchange sometimes returns an error body with a 200 status. The client converts these into thrown errors, which is the right behaviour but will look different from raw `curl` output if you are comparing the two.

> [accordion] get\_markets hides perpetual-side failures
>
> If the perpetual side is unavailable, `get_markets` returns `{"perp":{"unavailable":"..."}}` rather than erroring — so an agent may report that no perpetual markets exist. Check for that key before believing an empty list.

## Still stuck

Contact [support](https://docs.yellow.pro/community-and-resources/contact-support.md), or open an issue on [github.com/layer-3/yellow-pro-mcp](https://github.com/layer-3/yellow-pro-mcp). Include the `serverInfo.version` from the handshake above so the version you are running is unambiguous.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.