Troubleshooting
Most setup problems fall into a handful of buckets. Find your symptom below. If you are stuck for more than a couple of minutes, the fastest check is one command:
HUMANCHAIN_API_KEY=hc_your_key_here humanchain-mcp doctorIt tells you whether your config loads, whether the Hub is reachable, and whether your key works, with a PASS or FAIL line for each.
Setup and connection
| Symptom | Likely cause | Fix |
|---|---|---|
humanchain-mcp: command not found | Not installed, or not on PATH | pip install humanchain-mcp (Python 3.10+). pipx install humanchain-mcp also works. |
| Server exits with “HUMANCHAIN_API_KEY is not set” | No key in the env | Put your key in the MCP config’s env block, or export HUMANCHAIN_API_KEY=hc_.... To test without a key, set HUMANCHAIN_MODE=sandbox. |
Agent shows no consult tool | The MCP server is loaded at agent startup | Fully quit and reopen the agent. Confirm with humanchain-mcp --version. |
doctor says “cannot reach … /health” | Wrong backend URL, or network | Default backend is https://hub.example.com. Check HUMANCHAIN_BACKEND if you overrode it. |
Errors from a consult
Each error is a typed code so your agent can branch on it.
| Code (HTTP) | Meaning | What to do |
|---|---|---|
humanchain_auth_error (401) | Key missing, invalid, or revoked | Mint a fresh key on the site and update your env block. |
humanchain_quota_exceeded (429) | You spent your free credits | The demo grants 100 credits. Check what is left with humanchain-mcp doctor (it prints your balance). Mint a new key to get a fresh allocation for testing. |
humanchain_validation_error (422) | An input is out of bounds | Question must be 10 to 4000 chars; target_responses 1 to 5; wait_seconds 10 to 1800. |
humanchain_timeout (504) | No response within wait_seconds and bypass_on_timeout was false | Raise wait_seconds, or set bypass_on_timeout: true to fall back to the LLM. |
humanchain_no_human_available (504) | require_human: true and no human answered in time | Expected when no expert is online for the domain. Drop require_human, or give it longer. |
humanchain_escalated (409) | consensus or all_must_agree did not reach agreement | Review, retry, or lower target_responses. |
humanchain_backend_error (500) | Transient server-side issue | Retry; it is safe with the same request. |
“It answered, but with the LLM, not a human”
That is expected when no calibrated human is online for your domain
tags. With bypass_on_timeout: true (the default) the Hub returns the
LLM fallback after wait_seconds, and provenance is llm_fallback.
Both are a successful round-trip. To force a human answer in the demo,
ask whoever is running it to answer as a seeded expert from the
contributor portal.
Hit a rough edge? Tell us
Send a quick note with: what you were doing, what you expected, what you got (copy the error line), and your OS and agent. Mailto template:
mailto:hello@hub.example.com?subject=HumanChain%20preview%20snagFaster setup paths if you have not seen them: the install guide, a complete working example, and the async tools.