hivecode-mcp 0.14.1 → 0.14.3

package/docs/TROUBLESHOOTING.md

@@ -1,105 +1,106 @@
-# Hivecode Troubleshooting & Error Code Guide
-
-This guide explains every error code (`Qxxx`) emitted by Hivecode CLI commands, bridges, sync engines, and MCP surfaces.
-
----
-
-## Error Codes Quick Reference
-
-| Code | Printed by | What was happening | What it means | How to fix it |
-|---|---|---|---|---|
-| `Q430` | `hive-relay-health.js`, `sync.js`, `limits.js` | Connecting to a relay or syncing files | The relay is at or near its total socket connection capacity (`limits.maxConnsTotal`, HTTP 503). | Wait for other participants to disconnect, or if self-hosting, raise `HIVE_MAX_CONNS_TOTAL` in the relay environment. |
-| `Q431` | `hive-relay-health.js`, `sync.js`, `limits.js` | Joining a room (`hive_join`, `branch`, or `sync`) | The room reached its per-room connection ceiling (HTTP 429; 8 connections on the free tier). Note that each concurrently synced file holds a connection. | Close idle files or agents. If self-hosting, raise `HIVE_SEATS` on the relay. |
-| `Q432` | `limits.js` | Sending room events or HTTP MCP requests at high frequency | Message rate limit exceeded (`msgsPerSec` sustained or burst limit). | Back off and pace messages; the rate limiter automatically resets after `retryMs`. |
-| `Q433` | `limits.js` | Sending an oversized frame or message to the relay | Frame payload exceeds the maximum byte limit (`frameCap`). | Reduce message size or split file changes into smaller chunks. |
-| `Q434` | `limits.js` | Transferring large data volume in a short interval | Byte transfer rate limit exceeded (`bytesPerSec` sustained). | The connection is throttled until the byte rate recovers; avoid batching massive binary edits at once. |
-| `Q438` | `hive-relay-health.js`, `sync.js`, `limits.js` | Opening or syncing multiple files across rooms | The relay reached its total open-file capacity across all participants (`maxChannelsTotal`, HTTP 503). | Release claimed files no longer being edited. If self-hosting, raise `HIVE_MAX_CHANNELS_TOTAL` on the relay. |
-| `Q439` | `hive-relay-health.js`, `sync.js` | One participant opening or syncing many files | A single participant exceeded the maximum allowed open files limit on the relay (HTTP 503). | Close or release files that are not actively being modified. |
-| `Q470` | `sync.js`, `hive-pr.js`, `hive-github.js` | Cause 1: Syncing a local folder (`sync.js`). Cause 2: Landing a PR from room files (`hive-pr.js`). | Cause 1: Another local process is already syncing this folder (PID recorded in lock file). Cause 2: Could not reach the relay behind the room link within 20s. | Cause 1: Check running processes (`ps` / Task Manager) and stop the duplicate sync process, or remove the stale lock if crashed. Cause 2: Check internet connection and verify the relay URL is reachable. |
-| `Q490` | `sync.js`, `hive-gate.js` | Releasing a file governed by a verification gate | The verification gate command exited with a non-zero exit code or could not be run. Release is refused; file remains with holder. | Inspect the gate test output, fix the failing test or build error, and re-run. Do not force-release unless intentional. |
-| `Q491` | `sync.js`, `hive-gate.js` | Releasing a file governed by a verification gate | The verification gate command timed out before completing. Release is refused; file remains with holder. | Optimize the test suite to run faster, or adjust `timeoutMs` in the gate configuration. |
-| `Q492` | `hive-gate.js` | An operator force-releasing a file (`--force`) | Notice: a file was force-released without passing its verification gate. | Review the force-release reason posted in room chat to understand why tests were bypassed. |
-| `Q500` | `hive-pr.js` | Running `npx hivecode-mcp pr` | Target directory is not a git repository (missing `.git`). | Run the command from the root of a git repository clone. |
-| `Q501` | `hive-pr.js`, `hive-branch.js` | Running `pr` to land changes from the room | Nothing was attributed to commit (zero changes or no files modified by participants). | Verify that agents have edited files in the room before creating a PR. |
-| `Q502` | `hive-pr.js` | Running `pr` to land changes onto a new branch | Git branch creation failed (`git checkout -b <branch>`). | Check git status, resolve branch conflicts, or verify that the local git repository is in a clean state. |
-| `Q503` | `hive-pr.js` | Running `pr` to land attributed changes | Git commit failed (`git commit`) for an author attribution group. | Ensure `git config user.name` and `user.email` are set, and check for commit hook failures. |
-| `Q504` | `hive-pr.js` | Running `pr` to push changes to remote | Git push failed (`git push origin <branch>`). | Check remote permissions, network connectivity, and ensure authentication to GitHub/git remote is configured. |
-| `Q505` | `hive-pr.js` | Running `pr` to open a pull request | `gh pr create` failed when creating the pull request on GitHub. | Verify `gh auth status` and ensure the repository has a valid upstream remote on GitHub. |
-| `Q506` | `hive-pr-staleness.js` | Running `pr` to land changes | Refusing to write because the git branch moved upstream while agents were working (stale branch base). | Fetch latest changes from the branch (`git pull --ff-only` or merge), reconcile diverged files, and re-run `pr`. |
-| `Q507` | `hive-pr.js`, `hive-github.js` | Landing room work into a pull request | Partial room arrival: not all room files arrived before timeout during landing. Refusing to land incomplete work. | Ensure all agents have completed file synchronization, check network connectivity to relay, and re-run `pr`. |
-| `Q510` | `hive-mcp-http.js` | Starting `slack mcp-server` in `--auth slack` mode | `SLACK_SIGNING_SECRET` environment variable is missing. | Copy your Signing Secret from Slack App Settings (**Basic Information → App Credentials**) and set `SLACK_SIGNING_SECRET`. |
-| `Q511` | `hive-mcp-http.js` | Sending an HTTP request to `slack mcp-server` | HTTP request is missing the required `X-Slack-Signature` or `X-Slack-Request-Timestamp` headers. | Ensure the client sending requests is an official Slack webhook or computes valid Slack HMAC signatures. |
-| `Q512` | `hive-mcp-http.js` | Sending an HTTP request to `slack mcp-server` | Request timestamp is outside the 5-minute replay window. | Synchronize system clock with NTP and ensure requests are not delayed or replayed. |
-| `Q513` | `hive-mcp-http.js` | Sending an HTTP request to `slack mcp-server` | HMAC-SHA256 signature does not match the request payload. | Verify that `SLACK_SIGNING_SECRET` matches the Slack app sending the request. |
-| `Q514` | `hive-mcp-http.js` | Calling `hive_pause` or `hive_resume` via HTTP MCP | Specified participant name does not exist in the room. | Check `hive_members` to see current participants and use an exact name from the "Here now" list. |
-| `Q515` | `hive-mcp-http.js` | Calling a tool on `slack mcp-server` | Unknown tool name requested. | Use only supported tools: `hive_status`, `hive_members`, `hive_tasks`, `hive_claims`, `hive_recent`, `hive_pause`, `hive_resume`, `hive_say`. |
-| `Q516` | `hive-mcp-http.js` | Executing a tool on `slack mcp-server` | Tool execution threw an unhandled error. | Read the error message following `Q516` for specific tool diagnostics. |
-| `Q517` | `hive-mcp-http.js` | Sending JSON-RPC request to `slack mcp-server` | Method is not supported (only `initialize`, `tools/list`, and `tools/call` are supported). | Send valid JSON-RPC 2.0 MCP requests. |
-| `Q518` | `hive-mcp-http.js` | Sending GET or non-POST HTTP request to `slack mcp-server` | The MCP HTTP server endpoint accepts `POST` requests only. | Send HTTP `POST` requests with JSON payload. |
-| `Q519` | `hive-mcp-http.js` | Sending an oversized request body to `slack mcp-server` | Request payload body exceeds the maximum size limit (1 MB). | Reduce request body size or break calls into smaller batches. |
-| `Q520` | `hive-mcp-http.js` | Sending request payload to `slack mcp-server` | Request body is malformed and could not be parsed as JSON. | Validate JSON formatting in request body. |
-| `Q521` | `hive-mcp-http.js` | Calling `hive_pause`, `hive_resume`, or `hive_say` via HTTP MCP | Refused by Slack actor check: caller is a guest, external Slack Connect user, or not in `--allow`. | Full members can pause; add member ID (`U…`) to `--allow` for resume and say actions. |
-| `Q550` | `hive-privacy.js` | Connecting to a relay | Connected relay fingerprint does not match the pinned relay for this machine. | Verify the relay URL. If relay legitimately changed, update the pin file (`~/.hive-pin` or configured pin path). |
-| `Q551` | `hive-privacy.js` | Connecting to the public relay | `HIVE_PRIVATE=1` is set in environment, refusing connections to the public relay. | Pass your private self-hosted relay URL via `--relay <url>` or unset `HIVE_PRIVATE`. |
-| `Q552` | `hive-privacy.js` | Verifying relay pin configuration | The relay pin file or format is malformed or corrupted. | Check the format of the relay pin file or delete and recreate it. |
-| `Q560` | `hive-branch.js` | Running `branch <name>` | Directory is not inside a git repository, or is the user's home directory. | Run the command inside a project git repository clone. |
-| `Q561` | `hive-branch.js` | Running `branch <name>` | Invalid git branch name provided. | Use a valid git branch name conforming to `git check-ref-format`. |
-| `Q562` | `hive-branch.js` | Joining a branch room or running `branch` | Branch has no Hivecode room recorded, or repository has no commits yet. | Commit files to the repository first, or create/record room mapping with `branch <name> --join "<link>"`. |
-| `Q563` | `hive-branch.js` | Running `branch <name>` | Git error: could not read commit tree or branch does not exist locally. | Fetch the branch from remote (`git fetch origin <branch>:<branch>`) or verify branch name. |
-| `Q564` | `hive-mcp.js`, `hive-branch.js` | Checkpointing room branch progress | Checkpoint marker update failed. | Check repository write permissions and verify `.git/config` is writable. |
-| `Q565` | `hive-branch.js`, `hive-github.js` | Seeding a branch room with files | Seed files did not finish publishing within timeout or could not reach relay. | Re-run the branch seed command; check network connection to the relay. |
-| `Q566` | `hive-branch.js` | Seeding a branch room | Fresh joiner did not receive the complete branch tree (missing or divergent files). | Ensure relay has sufficient open-file capacity and re-run branch seeding. |
-| `Q567` | `hive-branch.js` | Running `branch <name> --join "<link>"` | Provided join link is invalid, or branch is already bound to a different room. | Provide a valid `wss://relay|room` link, or remove existing binding with `git config --remove-section "hivecode.<branch>"`. |
-| `Q568` | `hive-branch.js` | Reseeding a branch room (`--reseed`) | Target directory is not a room folder made by Hivecode, or room is not empty. | Reseeding only refills an empty room after relay loss. Move directory aside manually if resetting. |
-| `Q569` | `hive-branch.js` | Binding a branch to a room | Could not write room binding to `.git/config`. | Check file permissions on `.git/config` and verify disk space. |
-| `Q570` | `hive-branch.js` | Landing branch PR | Could not fast-forward branch, or branch moved upstream while landing. | Pull latest upstream commits into local branch and re-run `pr`. |
-| `Q571` | `hive-branch.js` | Landing branch PR | Working tree has uncommitted changes on the checkout branch. | Commit or stash changes (`git stash`) before landing PR. |
-| `Q572` | `hive-branch.js` | Landing branch PR | The room deleted files that were changed on the branch upstream since seeded. | Restore deleted files in the room or delete them upstream on the branch manually. |
-| `Q573` | `hive-branch.js` | Landing branch PR | Local commits landed on branch successfully, but `git push` failed. | Check remote permissions and push manually (`git push origin <branch>`). |
-| `Q574` | `hive-branch.js` | Opening PR from branch | No base branch specified to open PR into, or `gh pr create` failed. | Pass `--base <branch>` or ensure `gh` is authenticated. |
-| `Q580` | `sync.js` | Syncing a room folder | Room directory was deleted or moved while sync was active. | Recreate the folder or re-join the room; files on teammates' clients were protected. |
-| `Q581` | `hive-mcp.js` | Joining a room (`hive_join`) | Participant name is already in use by another connected participant. | Choose a distinct display name via `--name` or in `hive_join`. |
-| `Q600` | `hive-github.js` | Running `github start` or watcher background polling | GitHub CLI (`gh`) not installed, `gh auth login` required, or token expired/HTTP 401. | Install GitHub CLI (`gh`), run `gh auth login`, or set valid `GH_TOKEN`. |
-| `Q601` | `hive-github.js` | Running `github start` | Directory not in git repo, in home directory repo, origin not github.com, repo 404/invisible, or account cannot push. | Run in repository clone, verify `git remote -v`, and ensure `gh auth status` shows account with push access. |
-| `Q602` | `hive-github.js` | Running `github start` | Agent CLI not installed on PATH, invalid `--max-runs`, or missing `mcp__hivecode` in `--allowedTools`. | Install agent CLI, run `npx hivecode-mcp setup`, and ensure `--allowedTools` includes `mcp__hivecode`. |
-| `Q603` | `hive-github.js` | Watcher contacting GitHub API | Network failure reaching api.github.com or non-401 HTTP error. | Check internet connectivity and GitHub status; watcher automatically retries with backoff. |
-| `Q604` | `hive-github.js` | Watcher polling issues or PRs | GitHub secondary API rate limit hit. | Watcher automatically pauses and waits until rate limit resets before resuming. |
-| `Q605` | `hive-github.js` | Running `github start` | A watcher process is already running for this repository clone (lock held). | Stop the existing watcher process (PID named in message), or remove stale `.git/hivecode/watcher.lock`. |
-| `Q606` | `hive-github.js` | Watcher reading state | State file `.git/hivecode/github-watcher.json` is corrupted. | The corrupted state file is moved aside automatically, and watcher rebuilds state from GitHub. |
-| `Q607` | `hive-github.js` | Watcher picking up issue | Branch name collision: exhausted 50 suffix attempts (`hivecode/issue-N-49`). | Delete old merged issue branches on GitHub and locally. |
-| `Q608` | `hive-github.js` | Running `github start` | Repository has more than 5,000 files, exceeding public relay capacity. | Use your own self-hosted relay with `--relay <url>`, or pass `--allow-large`. |
-| `Q609` | `hive-github.js` | Running `github start` with `--notify` or `HIVE_NOTIFY_WEBHOOK` | The webhook given is not a web address (it must start with https:// or http://). | Copy the channel's incoming-webhook URL again from Slack or Discord. |
-| `Q610` | `hive-github.js` | Watcher fetching branches | Git remote error: could not list or fetch branches from origin. | Check network connection, git credentials, and remote repository existence. |
-| `Q611` | `hive-github.js` | Watcher creating issue branch | Branch diverged (commits on GitHub and local that are not in each other) or branch creation failed. | Reconcile branches manually and comment `/hivecode retry` on the issue. |
-| `Q612` | `hive-github.js` | Watcher updating checkpoint | Marker update failed during watcher run. | Check disk space and permissions in `.git/hivecode`. |
-| `Q630` | `hive-slack.js`, `hive-slack-agent.js`, `hive-mcp-http.js` | Starting Slack bridge, agent, check, or HTTP MCP | `SLACK_BOT_TOKEN` is missing, rejected (`invalid_auth`), or revoked. | Copy `xoxb-…` Bot Token from Slack App settings (**OAuth & Permissions**) and set `SLACK_BOT_TOKEN`. |
-| `Q631` | `hive-slack.js` | Starting Slack bridge or `slack check` | Missing `--channel`, channel not found, or bot not invited. | Pass `--channel <id>` and run `/invite @Hivecode` in the target Slack channel. |
-| `Q632` | `hive-slack.js` | Starting `slack start` | Another Slack bridge with the same name is already running in the room. | Stop the other bridge before starting a new one, or pass a different `--name`. |
-| `Q633` | `hive-github.js` | Starting `github start --slack-channel` | Slack bridge failed to load, missing `SLACK_BOT_TOKEN`, or missing `makeSlackThreader`. | Ensure `SLACK_BOT_TOKEN` is set and `hivecode-mcp` installation is intact. |
-| `Q634` | `hive-github.js`, `hive-slack.js`, `hive-slack-agent.js`, `hive-mcp-http.js` | Cause 1: Missing scopes (`users:read`, `channels:history`, `groups:history`, `assistant:write`). Cause 2: Missing or invalid `SLACK_APP_TOKEN` (`xapp-…`). Cause 3: Invalid allowlist member ID (not `U…`/`W…`). Cause 4: Socket Mode connection failed or timed out after retries. | Reinstall Slack app with appropriate manifest (`slack-app-manifest-inbound.json` or `-agent.json`), set `SLACK_APP_TOKEN`, use valid member IDs from Slack profiles, and verify network connectivity to Slack. |
-| `Q635` | `hive-slack.js` | Starting `slack start`, `slack agent`, or `github start --slack-allow` | Multi-connection collision: another process is already connected to Slack Socket Mode with this `SLACK_APP_TOKEN`. Slack splits events across connections, causing "stop" commands to be dropped. | Stop the other running bridge or watcher process, or use a dedicated Slack app for each bridge. If a bridge was recently stopped, wait 60s for Slack to release the connection and retry. |
-| `Q636` | `hive-slack.js`, `hive-slack-agent.js`, `hive-mcp-http.js` | Preflight Slack check, Slack bridge start, or `github start --slack-channel` | Network unreachable: failed to connect to Slack Web API (`fetch failed`, DNS error, or request timeout). The Slack token was not rejected because Slack could not be reached. | Check network connectivity, DNS, and proxy settings, then retry. |
-| `Q637` | `hive-mcp.js` | Running `hive_join` | This MCP server process is already in use by another agent with a different name. Some host apps (Antigravity, Cursor, Claude Desktop) share one MCP server process across all chat tabs. | Do not leave or rejoin. Add a second MCP server entry in your app's MCP config (e.g. `hivecode-2`) and restart the app (`docs/JOIN_WITH_AGENT.md`). If you are the same agent switching rooms, rejoin using the original name. |
-| `Q640` | `hive-notify.js` | Running `notify` | Provided link is not a valid room link (must be `wss://relay|room-…`). | Pass a valid room join link. |
-| `Q641` | `hive-notify.js` | Running `notify` | Missing `--webhook <url>` argument. | Provide incoming webhook URL from Slack or Discord. |
-| `Q642` | `hive-notify.js` | Running `notify` | Missing `--for <name>` argument or non-positive `--every` interval. | Specify who to notify with `--for <name>` and positive minutes with `--every <minutes>`. |
-| `Q643` | `hive-notify.js` | Running `notify` | The webhook endpoint refused the initial test post. | Check the webhook URL and ensure the receiving service is accessible. |
-| `Q644` | `hive-notify.js` | Running `notify` | A notifier is already running for this room (lock file held by another process). | Stop the other running notifier process or let it run. |
-| `Q575` | `hive-land.js` | Landing branch changes into a pull request (`hive_land` / `landIssue`) | A file claim is still held by a participant (or appeared during landing). All files must be released before landing. | Release all held files using `hive_release`, or wait for the holder to finish and release their claims. |
-| `Q576` | `hive-land.js` | Running project tests during landing verification (`--test "<command>"`) | The verification tests failed, timed out, or test checkout was not at the exact commit being landed. | Inspect test error output in room task or log. If tests require uncommitted files or dependencies, pass `--test-copy <files>` or `--test-setup <cmd>`, or fix failing test code. |
-| `Q577` | `hive-land.js` | Landing branch changes into a pull request | The room holds no files or landing would delete most branch files (>50% mass deletion). Indicates relay restarted or room was wiped. | Reconnect agents to reseed the room, reseed from branch (`branch <name> --reseed`), or pass `--allow-mass-delete` if intentional. |
-| `Q578` | `hive-land.js` | Pushing landed commits to remote origin (`git push origin <branch>`) | Pre-push checks failed: `origin` remote missing or unreachable, remote branch ahead, workflow files modified without `--allow-workflow-changes`, or secrets detected. | Ensure `origin` is configured and accessible, pull latest branch commits, or remove secrets/workflow changes from landed files. |
-| `Q579` | `hive-land.js` | Starting a landing run for a branch | Another landing run for this branch is currently active (landing lock held). | Wait for the concurrent landing to finish, or remove stale landing lock if the prior process crashed. |
-| `Q582` | `hive-repos.js` | Running `pr` from within a room | The room's repository folder is not located on this local machine. | Run `pr` from the machine where the repository clone resides, or register the repository with `hive-repos`. |
-| `Q583` | `hive-repos.js`, `hive-branch.js` | Running `pr` to land changes from a room | No local git repository is registered or bound to this room on this machine. | In your repository checkout, run `npx hivecode-mcp branch <branch>` to bind the room to your repository. |
-| `Q584` | `hive-repos.js` | Looking up registered repository for room | Repository registration is stale (folder moved/deleted) or multiple local clones are registered for the same room. | Re-bind the correct repository clone using `npx hivecode-mcp branch <branch>`, or remove obsolete entries in `~/.hivecode/repos.json`. |
-| `Q585` | `hive-repos.js` | Calling `hive_pr` | Not currently connected to a room (`hive_join` has not been called). | Join a room first using `hive_join` before calling `hive_pr`. |
-| `Q586` | `hive-repos.js` | Calling `hive_pr` | Room connection is currently offline or disconnected from relay. | Wait for the room connection to reconnect to the relay before running `hive_pr`. |
-| `Q650` | `hive-room-mode.js` | Starting room-mode watcher (`github start --room "<link>"`) | Missing, empty, or malformed room join link. | Provide a valid room join link (`wss://<relay>|room-<id>`) or use `github start --branch <name>`. |
-| `Q651` | `hive-room-mode.js` | Starting room-mode watcher | Target directory is not a git repository root (or is the user's home directory). | Run the watcher from inside a valid git repository checkout. |
-| `Q652` | `hive-room-mode.js` | Starting room-mode watcher | The specified room is not bound to a git branch in this repository, or multiple branches match. | Run `npx hivecode-mcp branch <branch>` to bind the branch, or launch with `github start --branch <branch>`. |
-| `Q653` | `hive-room-mode.js` | Preflight check for room-mode watcher | GitHub CLI (`gh`) is not installed, not in `PATH`, or not authenticated. | Install `gh` and run `gh auth login` with write permissions to the repository. |
-| `Q654` | `hive-room-mode.js` | Preflight member version check for room mode | An active AI agent in the room is running a Hivecode version older than 0.13.0, or has no version declared. | Update all participating AI agent packages to `hivecode-mcp@latest` (>= 0.13.0) and reconnect. |
-| `Q655` | `hive-room-mode.js` | Starting room-mode watcher | Another room-mode watcher is already active for this room (watcher lock held). | Stop the other running watcher process, or remove the stale lock file in `.git/hive-room-watcher.lock` if crashed. |
-| `Q656` | `hive-room-mode.js` | Room-mode watcher connecting to relay | Could not connect to relay at specified URL, or connection timed out. | Verify internet connectivity, check relay status, and ensure the relay URL is correct. |
-| `Q657` | `hive-room-mode.js` | Dispatching an issue task or chat into room | Delivery verification failed: task assignment or chat message was not confirmed in room within timeout. | Check relay stability, ensure room has reachable participants, and retry with `/hivecode retry`. |
+# Hivecode Troubleshooting & Error Code Guide
+
+This guide explains every error code (`Qxxx`) emitted by Hivecode CLI commands, bridges, sync engines, and MCP surfaces.
+
+---
+
+## Error Codes Quick Reference
+
+| Code | Printed by | What was happening | What it means | How to fix it |
+|---|---|---|---|---|
+| `Q430` | `hive-relay-health.js`, `sync.js`, `limits.js` | Connecting to a relay or syncing files | The relay is at or near its total socket connection capacity (`limits.maxConnsTotal`, HTTP 503). | Wait for other participants to disconnect, or if self-hosting, raise `HIVE_MAX_CONNS_TOTAL` in the relay environment. |
+| `Q431` | `hive-relay-health.js`, `sync.js`, `limits.js` | Joining a room (`hive_join`, `branch`, or `sync`) | The room reached its per-room connection ceiling (HTTP 429; 8 connections on the free tier). Note that each concurrently synced file holds a connection. | Close idle files or agents. If self-hosting, raise `HIVE_SEATS` on the relay. |
+| `Q432` | `limits.js` | Sending room events or HTTP MCP requests at high frequency | Message rate limit exceeded (`msgsPerSec` sustained or burst limit). | Back off and pace messages; the rate limiter automatically resets after `retryMs`. |
+| `Q433` | `limits.js` | Sending an oversized frame or message to the relay | Frame payload exceeds the maximum byte limit (`frameCap`). | Reduce message size or split file changes into smaller chunks. |
+| `Q434` | `limits.js` | Transferring large data volume in a short interval | Byte transfer rate limit exceeded (`bytesPerSec` sustained). | The connection is throttled until the byte rate recovers; avoid batching massive binary edits at once. |
+| `Q438` | `hive-relay-health.js`, `sync.js`, `limits.js` | Opening or syncing multiple files across rooms | The relay reached its total open-file capacity across all participants (`maxChannelsTotal`, HTTP 503). | Release claimed files no longer being edited. If self-hosting, raise `HIVE_MAX_CHANNELS_TOTAL` on the relay. |
+| `Q439` | `hive-relay-health.js`, `sync.js` | One participant opening or syncing many files | A single participant exceeded the maximum allowed open files limit on the relay (HTTP 503). | Close or release files that are not actively being modified. |
+| `Q470` | `sync.js`, `hive-pr.js`, `hive-github.js` | Cause 1: Syncing a local folder (`sync.js`). Cause 2: Landing a PR from room files (`hive-pr.js`). | Cause 1: Another local process is already syncing this folder (PID recorded in lock file). Cause 2: Could not reach the relay behind the room link within 20s. | Cause 1: Check running processes (`ps` / Task Manager) and stop the duplicate sync process, or remove the stale lock if crashed. Cause 2: Check internet connection and verify the relay URL is reachable. |
+| `Q490` | `sync.js`, `hive-gate.js` | Releasing a file governed by a verification gate | The verification gate command exited with a non-zero exit code or could not be run. Release is refused; file remains with holder. | Inspect the gate test output, fix the failing test or build error, and re-run. Do not force-release unless intentional. |
+| `Q491` | `sync.js`, `hive-gate.js` | Releasing a file governed by a verification gate | The verification gate command timed out before completing. Release is refused; file remains with holder. | Optimize the test suite to run faster, or adjust `timeoutMs` in the gate configuration. |
+| `Q492` | `hive-gate.js` | An operator force-releasing a file (`--force`) | Notice: a file was force-released without passing its verification gate. | Review the force-release reason posted in room chat to understand why tests were bypassed. |
+| `Q500` | `hive-pr.js` | Running `npx hivecode-mcp pr` | Target directory is not a git repository (missing `.git`). | Run the command from the root of a git repository clone. |
+| `Q501` | `hive-pr.js`, `hive-branch.js` | Running `pr` to land changes from the room | Nothing was attributed to commit (zero changes or no files modified by participants). | Verify that agents have edited files in the room before creating a PR. |
+| `Q502` | `hive-pr.js` | Running `pr` to land changes onto a new branch | Git branch creation failed (`git checkout -b <branch>`). | Check git status, resolve branch conflicts, or verify that the local git repository is in a clean state. |
+| `Q503` | `hive-pr.js` | Running `pr` to land attributed changes | Git commit failed (`git commit`) for an author attribution group. | Ensure `git config user.name` and `user.email` are set, and check for commit hook failures. |
+| `Q504` | `hive-pr.js` | Running `pr` to push changes to remote | Git push failed (`git push origin <branch>`). | Check remote permissions, network connectivity, and ensure authentication to GitHub/git remote is configured. |
+| `Q505` | `hive-pr.js` | Running `pr` to open a pull request | `gh pr create` failed when creating the pull request on GitHub. | Verify `gh auth status` and ensure the repository has a valid upstream remote on GitHub. |
+| `Q506` | `hive-pr-staleness.js` | Running `pr` to land changes | Refusing to write because the git branch moved upstream while agents were working (stale branch base). | Fetch latest changes from the branch (`git pull --ff-only` or merge), reconcile diverged files, and re-run `pr`. |
+| `Q507` | `hive-pr.js`, `hive-github.js` | Landing room work into a pull request | Partial room arrival: not all room files arrived before timeout during landing. Refusing to land incomplete work. | Ensure all agents have completed file synchronization, check network connectivity to relay, and re-run `pr`. |
+| `Q510` | `hive-mcp-http.js` | Starting `slack mcp-server` in `--auth slack` mode | `SLACK_SIGNING_SECRET` environment variable is missing. | Copy your Signing Secret from Slack App Settings (**Basic Information → App Credentials**) and set `SLACK_SIGNING_SECRET`. |
+| `Q511` | `hive-mcp-http.js` | Sending an HTTP request to `slack mcp-server` | HTTP request is missing the required `X-Slack-Signature` or `X-Slack-Request-Timestamp` headers. | Ensure the client sending requests is an official Slack webhook or computes valid Slack HMAC signatures. |
+| `Q512` | `hive-mcp-http.js` | Sending an HTTP request to `slack mcp-server` | Request timestamp is outside the 5-minute replay window. | Synchronize system clock with NTP and ensure requests are not delayed or replayed. |
+| `Q513` | `hive-mcp-http.js` | Sending an HTTP request to `slack mcp-server` | HMAC-SHA256 signature does not match the request payload. | Verify that `SLACK_SIGNING_SECRET` matches the Slack app sending the request. |
+| `Q514` | `hive-mcp-http.js` | Calling `hive_pause` or `hive_resume` via HTTP MCP | Specified participant name does not exist in the room. | Check `hive_members` to see current participants and use an exact name from the "Here now" list. |
+| `Q515` | `hive-mcp-http.js` | Calling a tool on `slack mcp-server` | Unknown tool name requested. | Use only supported tools: `hive_status`, `hive_members`, `hive_tasks`, `hive_claims`, `hive_recent`, `hive_pause`, `hive_resume`, `hive_say`. |
+| `Q516` | `hive-mcp-http.js` | Executing a tool on `slack mcp-server` | Tool execution threw an unhandled error. | Read the error message following `Q516` for specific tool diagnostics. |
+| `Q517` | `hive-mcp-http.js` | Sending JSON-RPC request to `slack mcp-server` | Method is not supported (only `initialize`, `tools/list`, and `tools/call` are supported). | Send valid JSON-RPC 2.0 MCP requests. |
+| `Q518` | `hive-mcp-http.js` | Sending GET or non-POST HTTP request to `slack mcp-server` | The MCP HTTP server endpoint accepts `POST` requests only. | Send HTTP `POST` requests with JSON payload. |
+| `Q519` | `hive-mcp-http.js` | Sending an oversized request body to `slack mcp-server` | Request payload body exceeds the maximum size limit (1 MB). | Reduce request body size or break calls into smaller batches. |
+| `Q520` | `hive-mcp-http.js` | Sending request payload to `slack mcp-server` | Request body is malformed and could not be parsed as JSON. | Validate JSON formatting in request body. |
+| `Q521` | `hive-mcp-http.js` | Calling `hive_pause`, `hive_resume`, or `hive_say` via HTTP MCP | Refused by Slack actor check: caller is a guest, external Slack Connect user, or not in `--allow`. | Full members can pause; add member ID (`U…`) to `--allow` for resume and say actions. |
+| `Q550` | `hive-privacy.js` | Connecting to a relay | Connected relay fingerprint does not match the pinned relay for this machine. | Verify the relay URL. If relay legitimately changed, update the pin file (`~/.hive-pin` or configured pin path). |
+| `Q551` | `hive-privacy.js` | Connecting to the public relay | `HIVE_PRIVATE=1` is set in environment, refusing connections to the public relay. | Pass your private self-hosted relay URL via `--relay <url>` or unset `HIVE_PRIVATE`. |
+| `Q552` | `hive-privacy.js` | Verifying relay pin configuration | The relay pin file or format is malformed or corrupted. | Check the format of the relay pin file or delete and recreate it. |
+| `Q560` | `hive-branch.js` | Running `branch <name>` | Directory is not inside a git repository, or is the user's home directory. | Run the command inside a project git repository clone. |
+| `Q561` | `hive-branch.js` | Running `branch <name>` | Invalid git branch name provided. | Use a valid git branch name conforming to `git check-ref-format`. |
+| `Q562` | `hive-branch.js` | Joining a branch room or running `branch` | Branch has no Hivecode room recorded, or repository has no commits yet. | Commit files to the repository first, or create/record room mapping with `branch <name> --join "<link>"`. |
+| `Q563` | `hive-branch.js` | Running `branch <name>` | Git error: could not read commit tree or branch does not exist locally. | Fetch the branch from remote (`git fetch origin <branch>:<branch>`) or verify branch name. |
+| `Q564` | `hive-mcp.js`, `hive-branch.js` | Checkpointing room branch progress | Checkpoint marker update failed. | Check repository write permissions and verify `.git/config` is writable. |
+| `Q565` | `hive-branch.js`, `hive-github.js` | Seeding a branch room with files | Seed files did not finish publishing within timeout or could not reach relay. | Re-run the branch seed command; check network connection to the relay. |
+| `Q566` | `hive-branch.js` | Seeding a branch room | Fresh joiner did not receive the complete branch tree (missing or divergent files). | Ensure relay has sufficient open-file capacity and re-run branch seeding. |
+| `Q567` | `hive-branch.js` | Running `branch <name> --join "<link>"` | Provided join link is invalid, or branch is already bound to a different room. | Provide a valid `wss://relay|room` link, or remove existing binding with `git config --remove-section "hivecode.<branch>"`. |
+| `Q568` | `hive-branch.js` | Reseeding a branch room (`--reseed`) | Target directory is not a room folder made by Hivecode, or room is not empty. | Reseeding only refills an empty room after relay loss. Move directory aside manually if resetting. |
+| `Q569` | `hive-branch.js` | Binding a branch to a room | Could not write room binding to `.git/config`. | Check file permissions on `.git/config` and verify disk space. |
+| `Q570` | `hive-branch.js` | Landing branch PR | Could not fast-forward branch, or branch moved upstream while landing. | Pull latest upstream commits into local branch and re-run `pr`. |
+| `Q571` | `hive-branch.js` | Landing branch PR | Working tree has uncommitted changes on the checkout branch. | Commit or stash changes (`git stash`) before landing PR. |
+| `Q572` | `hive-branch.js` | Landing branch PR | The room deleted files that were changed on the branch upstream since seeded. | Restore deleted files in the room or delete them upstream on the branch manually. |
+| `Q573` | `hive-branch.js` | Landing branch PR | Local commits landed on branch successfully, but `git push` failed. | Check remote permissions and push manually (`git push origin <branch>`). |
+| `Q574` | `hive-branch.js` | Opening PR from branch | No base branch specified to open PR into, or `gh pr create` failed. | Pass `--base <branch>` or ensure `gh` is authenticated. |
+| `Q580` | `sync.js` | Syncing a room folder | Room directory was deleted or moved while sync was active. | Recreate the folder or re-join the room; files on teammates' clients were protected. |
+| `Q581` | `hive-mcp.js` | Joining a room (`hive_join`) | Participant name is already in use by another connected participant. | Choose a distinct display name via `--name` or in `hive_join`. |
+| `Q600` | `hive-github.js` | Running `github start` or watcher background polling | GitHub CLI (`gh`) not installed, `gh auth login` required, or token expired/HTTP 401. | Install GitHub CLI (`gh`), run `gh auth login`, or set valid `GH_TOKEN`. |
+| `Q601` | `hive-github.js` | Running `github start` | Directory not in git repo, in home directory repo, origin not github.com, repo 404/invisible, or account cannot push. | Run in repository clone, verify `git remote -v`, and ensure `gh auth status` shows account with push access. |
+| `Q602` | `hive-github.js` | Running `github start` | Agent CLI not installed on PATH, invalid `--max-runs`, or missing `mcp__hivecode` in `--allowedTools`. | Install agent CLI, run `npx hivecode-mcp setup`, and ensure `--allowedTools` includes `mcp__hivecode`. |
+| `Q603` | `hive-github.js` | Watcher contacting GitHub API | Network failure reaching api.github.com or non-401 HTTP error. | Check internet connectivity and GitHub status; watcher automatically retries with backoff. |
+| `Q604` | `hive-github.js` | Watcher polling issues or PRs | GitHub secondary API rate limit hit. | Watcher automatically pauses and waits until rate limit resets before resuming. |
+| `Q605` | `hive-github.js` | Running `github start` | A watcher process is already running for this repository clone (lock held). | Stop the existing watcher process (PID named in message), or remove stale `.git/hivecode/watcher.lock`. |
+| `Q606` | `hive-github.js` | Watcher reading state | State file `.git/hivecode/github-watcher.json` is corrupted. | The corrupted state file is moved aside automatically, and watcher rebuilds state from GitHub. |
+| `Q607` | `hive-github.js` | Watcher picking up issue | Branch name collision: exhausted 50 suffix attempts (`hivecode/issue-N-49`). | Delete old merged issue branches on GitHub and locally. |
+| `Q608` | `hive-github.js` | Running `github start` | Repository has more than 5,000 files, exceeding public relay capacity. | Use your own self-hosted relay with `--relay <url>`, or pass `--allow-large`. |
+| `Q609` | `hive-github.js` | Running `github start` with `--notify` or `HIVE_NOTIFY_WEBHOOK` | The webhook given is not a web address (it must start with https:// or http://). | Copy the channel's incoming-webhook URL again from Slack or Discord. |
+| `Q610` | `hive-github.js` | Watcher fetching branches | Git remote error: could not list or fetch branches from origin. | Check network connection, git credentials, and remote repository existence. |
+| `Q611` | `hive-github.js` | Watcher creating issue branch | Branch diverged (commits on GitHub and local that are not in each other) or branch creation failed. | Reconcile branches manually and comment `/hivecode retry` on the issue. |
+| `Q612` | `hive-github.js` | Watcher updating checkpoint | Marker update failed during watcher run. | Check disk space and permissions in `.git/hivecode`. |
+| `Q630` | `hive-slack.js`, `hive-slack-agent.js`, `hive-mcp-http.js` | Starting Slack bridge, agent, check, or HTTP MCP | `SLACK_BOT_TOKEN` is missing, rejected (`invalid_auth`), or revoked. | Copy `xoxb-…` Bot Token from Slack App settings (**OAuth & Permissions**) and set `SLACK_BOT_TOKEN`. |
+| `Q631` | `hive-slack.js` | Starting Slack bridge or `slack check` | Missing `--channel`, channel not found, or bot not invited. | Pass `--channel <id>` and run `/invite @Hivecode` in the target Slack channel. |
+| `Q632` | `hive-slack.js` | Starting `slack start` | Another Slack bridge with the same name is already running in the room. | Stop the other bridge before starting a new one, or pass a different `--name`. |
+| `Q633` | `hive-github.js` | Starting `github start --slack-channel` | Slack bridge failed to load, missing `SLACK_BOT_TOKEN`, or missing `makeSlackThreader`. | Ensure `SLACK_BOT_TOKEN` is set and `hivecode-mcp` installation is intact. |
+| `Q634` | `hive-github.js`, `hive-slack.js`, `hive-slack-agent.js`, `hive-mcp-http.js` | Cause 1: Missing scopes (`users:read`, `channels:history`, `groups:history`, `assistant:write`). Cause 2: Missing or invalid `SLACK_APP_TOKEN` (`xapp-…`). Cause 3: Invalid allowlist member ID (not `U…`/`W…`). Cause 4: Socket Mode connection failed or timed out after retries. | Reinstall Slack app with appropriate manifest (`slack-app-manifest-inbound.json` or `-agent.json`), set `SLACK_APP_TOKEN`, use valid member IDs from Slack profiles, and verify network connectivity to Slack. |
+| `Q635` | `hive-slack.js` | Starting `slack start`, `slack agent`, or `github start --slack-allow` | Multi-connection collision: another process is already connected to Slack Socket Mode with this `SLACK_APP_TOKEN`. Slack splits events across connections, causing "stop" commands to be dropped. | Stop the other running bridge or watcher process, or use a dedicated Slack app for each bridge. If a bridge was recently stopped, wait 60s for Slack to release the connection and retry. |
+| `Q636` | `hive-slack.js`, `hive-slack-agent.js`, `hive-mcp-http.js` | Preflight Slack check, Slack bridge start, or `github start --slack-channel` | Network unreachable: failed to connect to Slack Web API (`fetch failed`, DNS error, or request timeout). The Slack token was not rejected because Slack could not be reached. | Check network connectivity, DNS, and proxy settings, then retry. |
+| `Q637` | `hive-mcp.js` | Running `hive_join` | This MCP server process is already in use by another agent with a different name. Some host apps (Antigravity, Cursor, Claude Desktop) share one MCP server process across all chat tabs. | Do not leave or rejoin. Add a second MCP server entry in your app's MCP config (e.g. `hivecode-2`) and restart the app (`docs/JOIN_WITH_AGENT.md`). If you are the same agent switching rooms, rejoin using the original name. |
+| `Q640` | `hive-notify.js` | Running `notify` | Provided link is not a valid room link (must be `wss://relay|room-…`). | Pass a valid room join link. |
+| `Q641` | `hive-notify.js` | Running `notify` | Missing `--webhook <url>` argument. | Provide incoming webhook URL from Slack or Discord. |
+| `Q642` | `hive-notify.js` | Running `notify` | Missing `--for <name>` argument or non-positive `--every` interval. | Specify who to notify with `--for <name>` and positive minutes with `--every <minutes>`. |
+| `Q643` | `hive-notify.js` | Running `notify` | The webhook endpoint refused the initial test post. | Check the webhook URL and ensure the receiving service is accessible. |
+| `Q644` | `hive-notify.js` | Running `notify` | A notifier is already running for this room (lock file held by another process). | Stop the other running notifier process or let it run. |
+| `Q575` | `hive-land.js` | Landing branch changes into a pull request (`hive_land` / `landIssue`) | A file claim is still held by a participant (or appeared during landing). All files must be released before landing. | Release all held files using `hive_release`, or wait for the holder to finish and release their claims. |
+| `Q576` | `hive-land.js` | Running project tests during landing verification (`--test "<command>"`) | The verification tests failed, timed out, or test checkout was not at the exact commit being landed. | Inspect test error output in room task or log. If tests require uncommitted files or dependencies, pass `--test-copy <files>` or `--test-setup <cmd>`, or fix failing test code. |
+| `Q577` | `hive-land.js` | Landing branch changes into a pull request | The room holds no files or landing would delete most branch files (>50% mass deletion). Indicates relay restarted or room was wiped. | Reconnect agents to reseed the room, reseed from branch (`branch <name> --reseed`), or pass `--allow-mass-delete` if intentional. |
+| `Q578` | `hive-land.js` | Pushing landed commits to remote origin (`git push origin <branch>`) | Pre-push checks failed: `origin` remote missing or unreachable, remote branch ahead, workflow files modified without `--allow-workflow-changes`, or secrets detected. | Ensure `origin` is configured and accessible, pull latest branch commits, or remove secrets/workflow changes from landed files. |
+| `Q579` | `hive-land.js` | Starting a landing run for a branch | Another landing run for this branch is currently active (landing lock held). | Wait for the concurrent landing to finish, or remove stale landing lock if the prior process crashed. |
+| `Q582` | `hive-repos.js` | Running `pr` from within a room | The room's repository folder is not located on this local machine. | Run `pr` from the machine where the repository clone resides, or register the repository with `hive-repos`. |
+| `Q583` | `hive-repos.js`, `hive-branch.js` | Running `pr` to land changes from a room | No local git repository is registered or bound to this room on this machine. | In your repository checkout, run `npx hivecode-mcp branch <branch>` to bind the room to your repository. |
+| `Q584` | `hive-repos.js` | Looking up registered repository for room | Repository registration is stale (folder moved/deleted) or multiple local clones are registered for the same room. | Re-bind the correct repository clone using `npx hivecode-mcp branch <branch>`, or remove obsolete entries in `~/.hivecode/repos.json`. |
+| `Q585` | `hive-repos.js` | Calling `hive_pr` | Not currently connected to a room (`hive_join` has not been called). | Join a room first using `hive_join` before calling `hive_pr`. |
+| `Q586` | `hive-repos.js` | Calling `hive_pr` | Room connection is currently offline or disconnected from relay. | Wait for the room connection to reconnect to the relay before running `hive_pr`. |
+| `Q587` | `hive-land.js` | Landing a branch room (`pr`, `hive_pr`, room mode) | This clone's record of the commit the room was seeded from (git config `hivecode.<branch>.base`) differs from the room's own record. Landing uses it to tell an untouched file from one changed outside the room, so it refuses rather than guess. | If the room was reseeded from another clone, run `npx -y hivecode-mcp@latest branch <branch> --join "<room link>"` here to record the room's seed, then land again. |
+| `Q650` | `hive-room-mode.js` | Starting room-mode watcher (`github start --room "<link>"`) | Missing, empty, or malformed room join link. | Provide a valid room join link (`wss://<relay>|room-<id>`) or use `github start --branch <name>`. |
+| `Q651` | `hive-room-mode.js` | Starting room-mode watcher | Target directory is not a git repository root (or is the user's home directory). | Run the watcher from inside a valid git repository checkout. |
+| `Q652` | `hive-room-mode.js` | Starting room-mode watcher | The specified room is not bound to a git branch in this repository, or multiple branches match. | Run `npx hivecode-mcp branch <branch>` to bind the branch, or launch with `github start --branch <branch>`. |
+| `Q653` | `hive-room-mode.js` | Preflight check for room-mode watcher | GitHub CLI (`gh`) is not installed, not in `PATH`, or not authenticated. | Install `gh` and run `gh auth login` with write permissions to the repository. |
+| `Q654` | `hive-room-mode.js` | Preflight member version check for room mode | An active AI agent in the room is running a Hivecode version older than 0.13.0, or has no version declared. | Update all participating AI agent packages to `hivecode-mcp@latest` (>= 0.13.0) and reconnect. |
+| `Q655` | `hive-room-mode.js` | Starting room-mode watcher | Another room-mode watcher is already active for this room (watcher lock held). | Stop the other running watcher process, or remove the stale lock file in `.git/hive-room-watcher.lock` if crashed. |
+| `Q656` | `hive-room-mode.js` | Room-mode watcher connecting to relay | Could not connect to relay at specified URL, or connection timed out. | Verify internet connectivity, check relay status, and ensure the relay URL is correct. |
+| `Q657` | `hive-room-mode.js` | Dispatching an issue task or chat into room | Delivery verification failed: task assignment or chat message was not confirmed in room within timeout. | Check relay stability, ensure room has reachable participants, and retry with `/hivecode retry`. |