Skip to main content

Troubleshooting

Common issues with colabhive-mcp and how to fix them. Run colabhive-mcp test first — it diagnoses the 90% case.

colabhive-mcp: command not found​

Your PATH doesn't include where the binary was installed.

uvx users — you don't get a permanent binary; clients launch the server via uvx colabhive-mcp. If you want a permanent command:

pipx install colabhive-mcp

pipx users — ensure pipx is on PATH:

pipx ensurepath
# restart shell

"Invalid API key" / 401 Unauthorized​

Error: Authentication failed. Status 401. Check COLABHIVE_API_KEY.

Causes:

  1. Env var not set. Confirm: echo $COLABHIVE_API_KEY.
  2. Key was revoked. Check console.colabhive.com/keys.
  3. Key/environment mismatch — a test (sandbox) key against a prod --api-url, or vice versa. Match the key to the --api-url you point at.

Fix:

export COLABHIVE_API_KEY=hive_xxx
colabhive-mcp test

If the key was leaked or you're rotating, see Security.

"No tools available" in agent UI​

The client connected, but tools/list returned empty.

Run:

COLABHIVE_LOG_LEVEL=debug colabhive-mcp test

Look for:

  • Fetched manifest (0 tools) → server side returned no visible tools. Check your account has approved models (console.colabhive.com/models).
  • Fetched manifest (N tools) but client shows 0 → client filtered them all. Check:
    • COLABHIVE_ALLOW_TOOLS / COLABHIVE_DENY_TOOLS
    • COLABHIVE_ALLOW_KINDS
    • COLABHIVE_STABILITY (e.g., stable excludes beta and experimental)

Client launches the server but it dies immediately​

In Claude Desktop / Cursor logs you see "MCP server exited (1)".

Most common cause: missing COLABHIVE_API_KEY in the client's environment. The client doesn't inherit your shell env on macOS — you must specify the env in the client config:

Claude Desktop:

{
  "mcpServers": {
    "colabhive": {
      "command": "uvx",
      "args": ["colabhive-mcp@latest"],
      "env": { "COLABHIVE_API_KEY": "hive_xxx" }
    }
  }
}

Cursor: same shape under mcpServers.

If env is correct but it still dies, run it manually with logs:

uvx colabhive-mcp@latest 2> /tmp/mcp.log < /dev/null
# Ctrl-C, then:
cat /tmp/mcp.log

Tool calls time out​

Error: invocation polled 30 times without resolution (slug=...)

The underlying model is in a long warm-up. This is expected for latencyClass: batch (e.g., a text-to-video model like wan22-video) on first call.

Fix:

# Longer timeout
export COLABHIVE_POLL_MAX_WAIT=900     # 15 min
export COLABHIVE_SYNC_TIMEOUT=120

Or set --poll-max-wait 900 in the server CLI.

"Tool name not found in manifest"​

The agent invoked a tool the server doesn't know about. Causes:

  1. Stale cache. Server manifest is older than your training. Restart the server, or wait manifest_ttl (default 5 min), or force: 
    curl -X POST http://127.0.0.1:8765/admin/manifest/refresh   # serve mode
  2. Filtered out. Check your allow/deny config.
  3. Renamed. Tools can be deprecated and replaced. Check deprecation.replacedBy in the manifest of the closest match.

Rate limit (429)​

Error: 429 Too Many Requests. Retry-After: 12s

Server-side per-account rate limit hit. Options:

  • Wait the indicated Retry-After.
  • Reduce concurrency in the agent (most clients respect Retry-After).
  • Upgrade your plan (console.colabhive.com/billing).
  • Set a client-side cap: 
    colabhive-mcp serve --max-calls-per-minute 30

"Connection refused" / network errors​

httpx.ConnectError: All connection attempts failed

Causes:

  1. No internet / DNS — ping api.colabhive.com.
  2. Corporate proxy. Set HTTPS_PROXY=http://proxy:8080.
  3. Cert pinning failed (advanced) — verify --cert-pin matches the server's leaf cert SHA-256.
  4. ColabHive incident — check status.colabhive.com.

High log noise in client​

The server defaults to info level. Clients sometimes display server stderr verbatim, which clutters the UI.

export COLABHIVE_LOG_LEVEL=warning
# or for full silence on stdout/stderr in stdio mode:
export COLABHIVE_LOG_LEVEL=error

In serve mode, redirect logs:

colabhive-mcp serve --log-file /var/log/colabhive-mcp.log

Trained model invocation returns wrong shape​

The agent passed {"text": "..."} but the trained model expects {"features": {"text": "..."}}.

This is a manifest validation gap. Inspect the manifest:

curl -H "X-API-Key: $KEY" https://api.colabhive.com/api/builder/v1/mcp/manifest/<slug> | jq .inputSchema

If inputSchema is wrong, fix it in console.colabhive.com/models/<slug>/manifest. The agent will see the new schema after the next refresh.

"Output too large"​

Some agent UIs cap MCP tool outputs (e.g., 64 KB). A web-fetch-public of a long page can overflow.

The server truncates payloads > --max-output-bytes (default 256 KB) and adds a notice:

[...output truncated. Original size: 1.2 MB. Use `web-scrape-public` with selectors for structured extraction.]

For specific tools, prefer the more focused variant (web-scrape-public over web-fetch-public).

Debugging an MCP session end-to-end​

# 1. Verify server-side reachability + auth
colabhive-mcp test

# 2. Run server in stdio mode + dump JSON-RPC
uvx colabhive-mcp@latest --log-level debug --log-jsonrpc 2> /tmp/mcp-jsonrpc.log < /dev/null

# 3. In another terminal, simulate a client
{
  echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2026-01-01","capabilities":{},"clientInfo":{"name":"manual","version":"0"}}}'
  echo '{"jsonrpc":"2.0","method":"initialized","params":{}}'
  echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
} | uvx colabhive-mcp@latest --log-level debug

You'll see every JSON-RPC frame in/out.

Still stuck?​

  1. GitHub Discussions — github.com/colabhive/colabhive-mcp/discussions
  2. Email — support@colabhive.com with:
    • colabhive-mcp --version
    • OS + Python version (python --version)
    • Sanitized output of colabhive-mcp test (remove your account ID if you wish)
    • Last 100 lines of the server log
  3. Security issues — security@colabhive.com (see Security)