# Troubleshooting

This guide is organized by **symptom** (what you see) rather than component. Find your error message and follow the diagnostic steps.

## Quick Diagnostics

Run this one-liner to get a full system status:

```bash
echo "=== Port 7910 (nREPL) ===" && nc -zv localhost 7910 2>&1
echo "=== Port 8000 (Chroma) ===" && nc -zv localhost 8000 2>&1
echo "=== Port 9999 (WebSocket) ===" && nc -zv localhost 9999 2>&1
echo "=== Port 11434 (Ollama) ===" && nc -zv localhost 11434 2>&1
echo "=== hive-mcp Process ===" && pgrep -fa "hive-mcp.*clojure"
echo "=== Emacs Server ===" && emacsclient -e '(emacs-version)' 2>&1
echo "=== Lock File ===" && cat ~/.config/hive-mcp/starting.lock 2>/dev/null || echo "No lock"
echo "=== Recent Errors ===" && tail -20 ~/.config/hive-mcp/server.log 2>/dev/null || echo "No log"
```

---

## MCP Connection Issues

### Symptom: `/mcp` shows `emacs · ✘ failed`

**What you see in Claude Code:**
```
emacs · ✘ failed
```

**Diagnostic steps:**

1. **Check the server log (most important!):**
   ```bash
   cat ~/.config/hive-mcp/server.log
   ```
   This reveals JVM errors that bb-mcp hides.

2. **Test bb-mcp directly:**
   ```bash
   echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | timeout 10 bb -m bb-mcp.core 2>&1
   ```

   **Expected output if working:**
   ```
   bb-mcp: ready {...}
   bb-mcp: connected to hive-mcp on port 7910
   {"jsonrpc":"2.0","id":1,"result":{...}}
   ```

**Solutions:**

**Simple:** Kill stale processes and restart:
```bash
kill $(pgrep -f "hive-mcp.*clojure") 2>/dev/null
rm ~/.config/hive-mcp/starting.lock 2>/dev/null
cd /path/to/hive-mcp && ./start-bb-mcp.sh --check
```

**Thorough:** Verify full startup chain:
```bash
# 1. Check bb-mcp location
echo $BB_MCP_DIR
ls $BB_MCP_DIR/bb.edn

# 2. Check hive-mcp compiles
cd /path/to/hive-mcp
clojure -M:dev -e "(require 'hive-mcp.server) (println :ok)"

# 3. Manual server start
nohup clojure -X:mcp >> ~/.config/hive-mcp/server.log 2>&1 &
sleep 5
nc -zv localhost 7910
```

---

### Symptom: "Cannot connect to Emacs server"

**What you see:**
```
error: Cannot connect to Emacs server
```

**Diagnostic:**
```bash
# Check if Emacs daemon is running
pgrep -f "emacs --daemon"

# Check server socket exists
ls /run/user/$(id -u)/emacs/server 2>/dev/null || ls /tmp/emacs$(id -u)/server 2>/dev/null
```

**Solutions:**

**Simple:** Start Emacs daemon:
```bash
emacs --daemon
emacsclient -e '(emacs-version)'  # Should print version
```

**If socket path is wrong:** Set in your `.emacs.d/init.el`:
```elisp
(setq server-socket-dir (format "/run/user/%d/emacs" (user-uid)))
(server-start)
```

---

### Symptom: "clojure: command not found"

**What you see:**
```bash
./start-bb-mcp.sh: line XX: clojure: command not found
```

**Solutions:**

**Linux:**
```bash
curl -L -O https://github.com/clojure/brew-install/releases/latest/download/linux-install.sh
chmod +x linux-install.sh
sudo ./linux-install.sh
```

**macOS:**
```bash
brew install clojure/tools/clojure
```

**Verify:**
```bash
clojure --version
```

---

### Symptom: "Unable to resolve symbol: X in this context"

**What you see in server.log:**
```
Syntax error compiling at (hive_mcp/chroma.clj:256:14).
Unable to resolve symbol: metadata-defaults in this context
```

**Cause:** Clojure forward reference - a symbol is used before it's defined.

**Solution:** This is a code bug. If you see this:
1. Check you have the latest code: `git pull`
2. If persists, file an issue with the exact error from `server.log`

---

### Symptom: Lock file stale

**What you see:**
```
bb-mcp: starting.lock exists, waiting...
```
(hangs indefinitely)

**Solution:**
```bash
rm ~/.config/hive-mcp/starting.lock
```

---

## Docker / Chroma Issues

### Symptom: "Connection refused" on port 8000

**What you see:**
```
Connection refused (localhost:8000)
```
or semantic search returns empty results.

**Diagnostic:**
```bash
# Check Chroma container
docker ps | grep chroma

# Check port binding
nc -zv localhost 8000

# Check Chroma health
curl http://localhost:8000/api/v1/heartbeat
```

**Solutions:**

**Simple:** Start Chroma:
```bash
cd /path/to/hive-mcp
docker compose up -d chroma
```

**Check logs if failing:**
```bash
docker logs emacs-mcp-chroma
```

**Permission issues:**
```bash
# Create volume with correct permissions
docker volume rm emacs-mcp_chroma-data 2>/dev/null
docker compose up -d chroma
```

---

### Symptom: "Volume not found" error

**What you see:**
```
ERROR: Volume emacs-mcp_milvus-etcd declared as external, but could not be found
```

**Cause:** External volumes for Milvus need to be created first.

**Solution:** Create the external volumes:
```bash
docker volume create emacs-mcp_milvus-etcd
docker volume create emacs-mcp_milvus-minio
docker volume create emacs-mcp_milvus-data
```

Or just start Chroma without Milvus:
```bash
docker compose up -d chroma  # Only Chroma, not full stack
```

---

### Symptom: Docker permission denied

**What you see:**
```
permission denied while trying to connect to the Docker daemon socket
```

**Solution:**
```bash
sudo usermod -aG docker $USER
# Log out and back in, or:
newgrp docker
```

---

### Symptom: "Port 8000 already in use"

**What you see:**
```
Error starting userland proxy: listen tcp4 0.0.0.0:8000: bind: address already in use
```

**Diagnostic:**
```bash
# Find what's using port 8000
sudo lsof -i :8000
```

**Solutions:**

**Kill the conflicting process:**
```bash
sudo kill $(sudo lsof -t -i :8000)
docker compose up -d chroma
```

**Or change Chroma's port** in `docker-compose.yml`:
```yaml
  chroma:
    ports:
      - "8001:8000"  # Use 8001 instead
```

Then update Emacs config:
```elisp
(setq hive-mcp-chroma-port 8001)
```

---

## Ollama Issues

### Symptom: "Model not found" or empty response

**What you see:**
```
HTTP request failed: 404
```
or
```
model 'nomic-embed-text' not found
```

**Diagnostic:**
```bash
# Check Ollama is running
curl http://localhost:11434/api/tags

# List available models
ollama list
```

**Solutions:**

**Pull the required model:**
```bash
ollama pull nomic-embed-text:latest
```

**For agent delegation models:**
```bash
ollama pull devstral-small:24b   # Default for Ollama backend
# or
ollama pull qwen2.5-coder:14b    # Alternative
```

---

### Symptom: "Connection refused" on port 11434

**What you see:**
```
clojure.lang.ExceptionInfo: HTTP request failed {:status nil :url "http://localhost:11434/api/chat"}
```

**Diagnostic:**
```bash
# Check if Ollama is running
pgrep -f ollama
curl http://localhost:11434/api/tags
```

**Solutions:**

**Start Ollama:**
```bash
ollama serve &
# or if installed as service:
systemctl --user start ollama
```

**Install Ollama (if missing):**
```bash
curl -fsSL https://ollama.com/install.sh | sh
```

---

### Symptom: Ollama timeout during embedding

**What you see:**
```
java.net.SocketTimeoutException
```

**Cause:** Large text or slow hardware.

**Solution:** The default timeout is 300 seconds. If you hit this:
1. Try smaller text chunks
2. Use a smaller embedding model: `nomic-embed-text:latest` instead of larger models
3. Check system resources: `htop` or `nvidia-smi`

---

### Symptom: Out of memory when running models

**What you see:**
```
Error: model requires more memory than is available
```
or system becomes unresponsive.

**Diagnostic:**
```bash
# Check available RAM
free -h

# Check GPU memory (if using)
nvidia-smi
```

**Solutions:**

**Use smaller models:**
```bash
# Instead of 24b models:
ollama pull codellama:7b      # ~4GB
ollama pull nomic-embed-text  # ~274MB (embeddings only)
```

**Model size requirements:**
| Model | Size | RAM Required |
|-------|------|--------------|
| `nomic-embed-text` | 274MB | ~1GB |
| `codellama:7b` | 4GB | ~8GB |
| `codellama:13b` | 8GB | ~16GB |
| `devstral-small:24b` | 14GB | ~24GB |

**Close other applications** to free memory before running large models.

---

## OpenRouter Issues

### Symptom: "OpenRouter API key required"

**What you see:**
```
clojure.lang.ExceptionInfo: OpenRouter API key required {:env "OPENROUTER_API_KEY"}
```

**Solution:**

Add to your shell config (`~/.bashrc` or `~/.zshrc`):
```bash
export OPENROUTER_API_KEY="sk-or-v1-..."
```

Then reload:
```bash
source ~/.bashrc
```

Get your key at: https://openrouter.ai/keys

---

### Symptom: OpenRouter API error 401/403

**What you see:**
```
OpenRouter API error: 401 - unauthorized
```

**Causes:**
- Invalid API key
- API key expired
- Account billing issue

**Solution:**
1. Verify key at https://openrouter.ai/keys
2. Check account credits
3. Generate a new key if needed

---

### Symptom: OpenRouter empty response

**What you see:**
```
OpenRouter returned empty response
```

**Cause:** Model returned no content (context window exceeded, content filter, etc.)

**Solutions:**

1. **Try a different model:**
   ```clojure
   (mcp__hive__openrouter_set_model "coding" "mistralai/devstral-2512:free")
   ```

2. **Check model mappings:**
   ```clojure
   (mcp__hive__openrouter_list_models)
   ```

---

### Symptom: "Model not valid" or model name format error

**What you see:**
```
OpenRouter API error: 400 - model not found
```

**Cause:** Using Ollama model format instead of OpenRouter format.

**Wrong (Ollama format):**
```
devstral-small:24b
codellama:13b
```

**Correct (OpenRouter format):**
```
mistralai/devstral-2512:free
meta-llama/codellama-13b-instruct
```

**Solution:**
```bash
# List available OpenRouter models
curl -s https://openrouter.ai/api/v1/models \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  | jq '.data[].id' | head -20
```

Common mappings:
| Task | OpenRouter Model |
|------|------------------|
| Coding | `mistralai/devstral-2512:free` |
| Architecture | `xiaomi/mimo-v2-flash:free` |
| Documentation | `openai/gpt-oss-120b:free` |

---

## Memory / Search Issues

### Symptom: Memory queries return empty

**What you see:**
```
[]
```
when you expected results.

**Diagnostic:**
```bash
# Check memory directory exists
ls ~/.emacs-mcp/memory/

# Check if entries exist for your project
ls ~/.emacs-mcp/memory/*.json
```

**Solutions:**

**Check project scope:** Memory is project-scoped. Make sure you're in the right project:
```elisp
M-x eval-expression RET
(hive-mcp-memory--project-id)
```

**Check memory file directly:**
```bash
cat ~/.emacs-mcp/memory/<project-hash>.json | jq '.'
```

---

### Symptom: Semantic search returns nothing but keyword search works

**What you see:** `mcp_memory_search_semantic` returns `[]` but `mcp_memory_query` with tags finds entries.

**Diagnostic:**
```bash
# Check Chroma is running
curl http://localhost:8000/api/v1/heartbeat

# Check Ollama embedding model
ollama list | grep nomic
```

**Causes:**
1. Chroma not running
2. Embedding model not pulled
3. Entries not indexed in Chroma

**Solution:** Re-index memory entries:
```elisp
;; From Emacs
M-x hive-mcp-chroma-reindex
```

---

### Symptom: "Wrong type argument: listp" during memory query

**What you see:**
```
*ERROR*: Wrong type argument: listp, ["tag1" "tag2" ...]
```

**Cause:** Corrupted memory entry with malformed tags.

**Solution:**

1. Find corrupted entries:
   ```elisp
   M-x eval-expression RET
   (let ((bad '()))
     (maphash
      (lambda (key entries)
        (dolist (entry entries)
          (let ((tags (plist-get entry :tags)))
            (when (and (consp tags) (vectorp (cdr tags)))
              (push (plist-get entry :id) bad)))))
      hive-mcp-memory--cache)
     bad)
   ```

2. Delete or fix the corrupted entry.

See the [wrap workflow troubleshooting docs](../docs/troubleshooting/wrap-workflow.md) for detailed fix steps.

---

## Swarm / Ling Issues

### Symptom: "File conflict" blocking dispatch

**What you see:**
```
{:conflict {:file "/src/core.clj" :held-by "swarm-worker-123"}}
```

**Cause:** Another ling has claimed the file.

**Diagnostic:**
```clojure
;; List all claims
(mcp__hive__claim_list)
```

**Solutions:**

**Wait for the other task:** Claims auto-release on completion.

**Clear stale claims:** If the claiming ling is dead:
```clojure
(mcp__hive__claim_cleanup {:dry_run false})
```

**Force clear specific file:**
```clojure
(mcp__hive__claim_clear {:file_path "/src/core.clj" :force true})
```

---

### Symptom: Ling spawn hangs or fails silently

**Diagnostic:**
```bash
# Check swarm status
(mcp__hive__swarm_status)

# Check for process
pgrep -f "claude.*swarm"
```

**Solutions:**

**Check terminal backend:**
```elisp
M-x eval-expression RET
hive-mcp-swarm-terminal
```

Should be one of: `claude-code-ide`, `vterm`, `eat`

**Resource guard:** If memory is tight, spawns may fail:
```clojure
(mcp__hive__resource_guard)
```

---

### Symptom: "hivemind_shout" not reaching coordinator

**Diagnostic:**
```clojure
;; Check coordinator status
(mcp__hive__hivemind_status {:directory "/path/to/project"})

;; Check WebSocket channel
(hive-mcp-channel-ws-connected-p)  ;; In Emacs
```

**Cause:** WebSocket channel not connected.

**Solution:** See WebSocket Channel Issues below.

---

## WebSocket Channel Issues

### Symptom: Channel not connected / push events not received

**What you see:** `hivemind_shout` succeeds but no messages appear in coordinator.

**Diagnostic:**
```bash
# Check WebSocket server port
nc -zv localhost 9999

# In Emacs
M-x eval-expression RET
(hive-mcp-channel-ws-connected-p)
```

**Solutions:**

**Reconnect manually:**
```elisp
M-x hive-mcp-channel-ws-connect
```

**Check configuration:**
```elisp
M-x eval-expression RET
hive-mcp-channel-ws-url  ;; Should be "ws://localhost:9999"
```

**Check hive-mcp server has WebSocket enabled:** The server must be started with WebSocket support. Check `~/.config/hive-mcp/server.log` for:
```
WebSocket server started on port 9999
```

---

### Symptom: "websocket.el not found"

**What you see:**
```
Cannot open load file: websocket
```

**Solution:**

Install websocket.el:

**Doom Emacs:**
```elisp
;; packages.el
(package! websocket)
```
Then `doom sync`.

**use-package:**
```elisp
(use-package websocket :ensure t)
```

---

## Emacs Configuration Issues

### Symptom: "Cannot open load file: hive-mcp-swarm-events"

**What you see:**
```
Cannot open load file: No such file or directory, hive-mcp-swarm-events
```

**Cause:** Load-path order wrong - addons directory not added, or added after `require`.

**Solution:**
```elisp
;; CORRECT: Add paths BEFORE require
(add-to-list 'load-path "/path/to/hive-mcp/elisp")
(add-to-list 'load-path "/path/to/hive-mcp/elisp/addons")
(require 'hive-mcp)  ; Now it can find submodules

;; WRONG: Require before paths
(require 'hive-mcp)  ; Fails
(add-to-list 'load-path ...)  ; Too late!
```

---

### Symptom: Duplicate events or "both channels" errors

**What you see:** Events appear twice, or connection errors on both ports 9998 and 9999.

**Cause:** Both legacy Unix socket channel and WebSocket channel are enabled.

**Solution:**
```elisp
;; Disable legacy channel (superseded by WebSocket)
(setq hive-mcp-channel-auto-connect nil)

;; Enable WebSocket (recommended)
(setq hive-mcp-channel-ws-auto-connect t)
```

---

### Symptom: Two nREPL servers / port 7910 conflict

**What you see:**
```
Address already in use: bind
```
or CIDER connects to wrong nREPL.

**Cause:** Both CIDER and MCP server trying to start nREPL on same port.

**Solution:**
```elisp
;; Don't start separate nREPL - MCP server embeds one
(setq hive-mcp-cider-auto-start-nrepl nil)

;; Connect to MCP's nREPL instead
(setq hive-mcp-cider-auto-connect t)
(setq hive-mcp-cider-nrepl-port 7910)
```

---

### Symptom: "Symbol's function definition is void: evil-define-key"

**What you see:**
```
Symbol's function definition is void: evil-define-key
```

**Cause:** In Doom Emacs, `hive-mcp-org-kanban` loads before evil mode.

**Solution:**
```elisp
;; CORRECT: Defer loading until evil is ready
(after! evil
  (require 'hive-mcp-org-kanban nil t))

;; WRONG: Load immediately
(require 'hive-mcp-org-kanban)  ; Fails in Doom
```

---

### Symptom: Rapid reconnect attempts at Emacs startup

**What you see:** Many "WebSocket connection failed" messages immediately after Emacs starts.

**Cause:** Emacs tries to connect before MCP server is ready.

**Solution:**
```elisp
;; Increase startup delay (default: 3.0)
(setq hive-mcp-channel-ws-startup-delay 5.0)  ; or 10.0 for slow systems
```

---

### Symptom: "doom sync" errors after adding packages

**What you see:**
```
Error: Failed to build package...
```
or missing packages after sync.

**Solutions:**

**Force package rebuild:**
```bash
doom sync -u  # Update and rebuild packages
```

**Clear cache if still failing:**
```bash
doom clean
doom sync
```

**Verify packages.el syntax:**
```elisp
;; packages.el should have:
(package! websocket)
(package! web-server)  ; Required by claude-code-ide
```

---

## Observability Stack Issues

### Symptom: Grafana shows "No data"

**What you see:** Dashboards display "No data" or empty panels.

**Diagnostic:**
```bash
# Check Prometheus can scrape hive-mcp
curl http://localhost:9999/metrics 2>/dev/null | head -5

# Check Prometheus targets
curl -s http://localhost:9090/api/v1/targets | jq '.data.activeTargets[].health'
```

**Causes:**
1. MCP server not exposing metrics endpoint
2. Prometheus can't reach the metrics endpoint
3. Wrong scrape configuration

**Solutions:**

**Check metrics endpoint exists:**
```bash
curl http://localhost:9999/metrics
# Should return Prometheus-format metrics
```

**Verify Prometheus config** (`config/prometheus.yml`):
```yaml
scrape_configs:
  - job_name: 'hive-mcp'
    static_configs:
      - targets: ['host.docker.internal:9999']
```

---

### Symptom: Logs not appearing in Loki

**What you see:** Loki queries return empty, or `promtail` errors.

**Diagnostic:**
```bash
# Check promtail can read logs
docker logs emacs-mcp-promtail

# Verify log file exists
ls -la ~/.config/hive-mcp/server.log
```

**Solutions:**

**Fix volume mount permissions:**
```bash
# Ensure promtail can read your logs
chmod 755 ~/.config/hive-mcp
chmod 644 ~/.config/hive-mcp/*.log
```

**Check promtail config** (`config/promtail.yml`):
```yaml
scrape_configs:
  - job_name: hive-mcp
    static_configs:
      - targets:
          - localhost
        labels:
          job: hive-mcp
          __path__: /var/log/hive-mcp/*.log
```

---

## Systemd Service Issues

### Symptom: `hive-mcp-nrepl.service` restart loop (status=200/CHDIR)

**What you see:**
```
systemctl --user status hive-mcp-nrepl.service
# restart counter is at 300+
# status=200/CHDIR
```

**Cause:** `WorkingDirectory` in the unit file points to a non-existent path.

**Solution:**
```bash
# Check the path
systemctl --user cat hive-mcp-nrepl.service | grep WorkingDirectory

# Fix it
systemctl --user edit hive-mcp-nrepl.service --full
# Change WorkingDirectory to correct path

systemctl --user daemon-reload
systemctl --user restart hive-mcp-nrepl.service
```

---

### Symptom: `hive-mcp-nrepl.service` fails with status=1

**What you see:**
```
Process: ExecStart=/usr/bin/clojure -M:nrepl (code=exited, status=1/FAILURE)
```

**Cause:** Wrong `clojure` binary. `/usr/bin/clojure` may be a stale install; the real CLI is at `/usr/local/bin/clojure`.

**Diagnostic:**
```bash
which clojure                    # Should be /usr/local/bin/clojure
/usr/bin/clojure --version       # May fail
/usr/local/bin/clojure --version # Should show version
```

**Solution:** Update `ExecStart` in the unit file to use `/usr/local/bin/clojure`.

---

### Symptom: MCP tools fail silently (wrong nREPL)

**What you see:** MCP tools return empty results, hivemind broadcasts go nowhere, but port 7910 appears to be up.

**Cause:** The systemd standalone nREPL grabbed port 7910 before the MCP server's embedded nREPL. bb-mcp connects to the standalone nREPL which has no channel, no events, no swarm state.

**Diagnostic:**
```bash
# Check which process owns port 7910
ss -tlnp | grep 7910

# If it's from hive-mcp-nrepl.service (not the MCP server), that's the problem
systemctl --user status hive-mcp-nrepl.service
```

**Solution:**
```bash
# Option 1: Stop the standalone service
systemctl --user stop hive-mcp-nrepl.service
systemctl --user disable hive-mcp-nrepl.service

# Option 2: Change the standalone service port
# Edit unit file, change ExecStart to use a different port
```

---

## Environment Issues

### Key Environment Variables

| Variable | Default | Purpose |
|----------|---------|---------|
| `BB_MCP_DIR` | `~/PP/bb-mcp` | Path to bb-mcp |
| `HIVE_MCP_DIR` | Script directory | Path to hive-mcp |
| `BB_MCP_NREPL_PORT` | `7910` | nREPL port |
| `OPENROUTER_API_KEY` | (none) | OpenRouter API key |
| `CHROMA_HOST` | `localhost` | Chroma server host |
| `CHROMA_PORT` | `8000` | Chroma server port |

### Symptom: Wrong project detected

**What you see:** Memory from wrong project, or project-id mismatch.

**Diagnostic:**
```elisp
M-x eval-expression RET
(hive-mcp-memory--project-id)
```

**Solution:** Create a `.hive-project.edn` file in your project root:
```clojure
{:project-id "my-stable-project-id"
 :name "My Project"}
```

Or generate one:
```clojure
(mcp__hive__generate_hive_project {:directory "/path/to/project"})
```

---

## Getting Help

If you're still stuck:

1. **Check the full server log:**
   ```bash
   cat ~/.config/hive-mcp/server.log
   ```

2. **Run pre-flight check:**
   ```bash
   ./start-bb-mcp.sh --check
   ```

3. **File an issue** with:
   - Exact error message
   - Output of quick diagnostics (top of this page)
   - Relevant portion of `~/.config/hive-mcp/server.log`

---

## Related Pages

- [[Installation]] - Initial setup guide
- [[Infrastructure-Setup]] - Docker, Ollama, OpenRouter configuration
- [[Emacs-Configuration]] - Elisp setup and addons
- [[Home]] - Wiki index