---
name: troubleshooting
description: Diagnose and fix common Mycelium installation and runtime issues. Use when encountering errors with mycelium commands, backend connectivity, Docker containers, LLM configuration, memory operations, or database migrations. Triggers on "not working", "error", "failed", "cannot connect", "troubleshoot", "debug", "fix".
---

# Mycelium Troubleshooting

Diagnose and fix common installation and runtime issues.

## Quick Diagnostics

Run `mycelium status --json` for machine-readable health data, or `mycelium status` for human-readable output. This checks backend, database, LLM, embedding, Docker, disk, and data directory.

## Common Issues

### 1. Command Not Found

**Symptom**: `mycelium: command not found`

**Fix**: Reinstall via one of these methods:

```bash
# curl
curl -fsSL https://mycelium-io.github.io/mycelium/install.sh | bash

# brew
brew install mycelium-io/tap/mycelium
```

Or via clawhub — tell your agent:
> "install https://clawhub.ai/juliarvalenti/mycelium-io"

Verify: `which mycelium` should show `~/.local/bin/mycelium`

If the binary exists but isn't found, add to PATH:
```bash
export PATH="$HOME/.local/bin:$PATH"
```

### 2. Backend Not Running

**Symptom**: `Cannot connect to Mycelium API at http://localhost:8000`

**Diagnosis**:
```bash
mycelium status          # quick check
docker ps | grep mycelium   # container status
```

**Fixes**:
- Start services: `mycelium up`
- Check logs: `mycelium logs mycelium-backend --tail 50`
- Rebuild: `mycelium up --build`

### 3. Config Not Found

**Symptom**: `Configuration file not found: ~/.mycelium/config.toml`

**Fix**:
```bash
mycelium init
```

Or with custom API URL:
```bash
mycelium init --api-url http://your-server:8000
```

### 4. Database Connection Failed

**Symptom**: Backend logs show `connection refused` or `could not connect to server`

**Diagnosis**:
```bash
docker ps | grep mycelium-db    # is container running?
docker logs mycelium-db --tail 20
```

**Fixes**:
- Wait for healthcheck: DB takes ~15s to initialize
- Check port conflict: `lsof -i :5432`
- Restart stack: `mycelium down && mycelium up`
- Nuclear option: `mycelium down --volumes && mycelium up` (destroys data)

### 5. Container Name Conflicts

**Symptom**: `container name "mycelium-db" is already in use`

**Fix**: The CLI handles this automatically, but if it persists:
```bash
docker rm -f mycelium-db mycelium-backend mycelium-graph-viewer
mycelium up
```

### 6. Port Already in Use

**Symptom**: `bind: address already in use`

**Diagnosis**:
```bash
lsof -i :8000   # backend port
lsof -i :5432   # database port
```

**Fixes**:
- Kill conflicting process
- Or use alternate ports in `~/.mycelium/.env`:
  ```
  MYCELIUM_BACKEND_PORT=8001
  MYCELIUM_DB_PORT=5433
  ```

### 7. LLM Not Configured

**Symptom**: `LLM unavailable — no API key configured`

**Fix**: Add to `~/.mycelium/.env`:
```bash
LLM_MODEL=anthropic/claude-sonnet-4-6
LLM_API_KEY=sk-ant-...
```

Or for local Ollama:
```bash
LLM_MODEL=ollama/llama3
LLM_BASE_URL=http://localhost:11434
```

Restart backend after changes: `mycelium down && mycelium up`

### 8. Memory Search Returns Nothing

**Symptom**: `mycelium memory search` returns empty despite memories existing

**Diagnosis**:
```bash
mycelium memory ls   # do memories exist?
ls ~/.mycelium/rooms/   # files present?
```

**Fixes**:
- Memories written directly (cat, editor) need reindex:
  ```bash
  mycelium reindex
  ```
- Check active room: `mycelium room ls` — wrong room selected?

### 9. No Active Room

**Symptom**: `No active room. Use 'mycelium room use <name>'`

**Fixes**:
```bash
mycelium room ls           # list available rooms
mycelium room use my-project   # set active room
```

Or pass room explicitly:
```bash
mycelium memory ls --room my-project
```

### 10. Migration Failures

**Symptom**: `alembic.util.exc.CommandError` or schema mismatch

**Note**: Migrations run automatically when the backend container starts. Manual migration is rarely needed.

**Diagnosis**:
```bash
mycelium logs mycelium-backend --tail 100   # check startup errors
```

**Fixes**:
- Restart the stack: `mycelium down && mycelium up`
- If schema is corrupted, reset: `mycelium down --volumes && mycelium up` (destroys data)
- Check backend logs for specific SQL errors

### 11. Docker Not Installed/Running

**Symptom**: `Docker not installed` or `Cannot connect to Docker daemon`

**Fixes**:
- Install Docker: https://docs.docker.com/get-docker/
- Start daemon: `sudo systemctl start docker`
- Add user to docker group: `sudo usermod -aG docker $USER` (logout/login required)

### 12. Image Pull Failures

**Symptom**: `manifest unknown` or `unauthorized`

**Fixes**:
- Login to ghcr: `docker login ghcr.io`
- Pull explicitly: `docker pull ghcr.io/mycelium-io/mycelium-backend:latest`
- Build from source: `mycelium up --build`

### 13. OpenClaw Agents Prompt for Approval on Mycelium Commands

**Symptom**: Agents display "Approval required" messages when trying to run mycelium commands like `mycelium await` / `mycelium respond`, or you see "You are not authorized to approve exec requests" in your chat channel.

**Cause**: OpenClaw's exec approval system blocks shell commands by default. The mycelium binary must be explicitly allowlisted.

**Fix**: Add mycelium to the exec approvals allowlist:

```bash
# For specific agents (recommended)
openclaw approvals allowlist add --agent "agent-alpha" "~/.local/bin/mycelium"
openclaw approvals allowlist add --agent "agent-beta" "~/.local/bin/mycelium"

# Or for all agents (convenient but less restrictive)
openclaw approvals allowlist add --agent "*" "~/.local/bin/mycelium"
```

Then restart the gateway:
```bash
openclaw gateway restart
# or: systemctl --user restart openclaw-gateway
```

**Verify**: Check `~/.openclaw/exec-approvals.json` contains the mycelium pattern in the allowlist.

**Note**: The allowlist pattern must be a full binary path (e.g., `~/.local/bin/mycelium`), not just the command name (`mycelium`).

### 14. OpenClaw CLI Commands Fail with "pairing required" or "device token mismatch"

**Symptom**: Running `openclaw logs`, `openclaw devices list`, or other gateway commands fails with errors like:
- `gateway connect failed: GatewayClientRequestError: pairing required`
- `unauthorized: device token mismatch (rotate/reissue device token)`

**Cause**: OpenClaw's gateway requires device authentication. The CLI needs to be "paired" (approved) before it can communicate with the gateway for operator-level commands.

**Fix**: 

1. List pending device pairing requests:
   ```bash
   openclaw devices list
   ```

2. Approve the pending request:
   ```bash
   openclaw devices approve <requestId>
   # Or approve the most recent request:
   openclaw devices approve --latest
   ```

### 15. Agent Behaving Strangely / "Why did it do that?"

**Symptom**: An agent took an unexpected action, replied with the wrong context, called the wrong tool, or burned a lot of tokens. `mycelium metrics show` rolls everything up into headline numbers but doesn't show *why* a specific turn behaved that way.

**Fix**: Drill into the actual span tree with `mycelium metrics traces`:

```bash
# 1. Find the recent spans for the agent
mycelium metrics traces list --agent=claire-agent --since=15m

# 2. Pick a trace_id from the output and render it as a tree.
#    Each row shows model, tokens, tool name, exit code, and any
#    error message, so you can see exactly which step went wrong.
mycelium metrics traces show <trace_id>

# 3. Want every attribute the OTel pipeline captured? (system prompt
#    chars, context window size, channel, trigger, etc.)
mycelium metrics traces show-attrs <span_id>
```

Other useful pivots when an agent looks off:

```bash
# What models is it actually calling?
mycelium metrics traces by-model --agent=claire-agent --since=1h

# Which rooms / channels has it been active in?
mycelium metrics traces by-room --agent=claire-agent --since=1h
mycelium metrics traces by-channel --agent=claire-agent --since=1h

# Tool call patterns (which tools, how often, error rate)
mycelium metrics traces by-tool --agent=claire-agent --since=1h

# Slowest turns (e.g. context assembly blowing up)
mycelium metrics traces slow --agent=claire-agent --since=1h

# Just the failures
mycelium metrics traces errors --agent=claire-agent --since=1h
```

If `mycelium metrics traces ...` reports `traces.db not found`, the OTLP
receiver isn't running on the hub — see issue #16.

## Configuration

Mycelium has two config systems: **config.toml** for CLI settings and **.env** for backend/Docker settings.

### CLI Settings (config.toml)

Stored in `~/.mycelium/config.toml` (global) and `./.mycelium/config.toml` (project-local).

| Setting | config.toml path | Env var override |
|---------|------------------|------------------|
| Backend URL | `server.api_url` | `MYCELIUM_API_URL` |
| Workspace ID | `server.workspace_id` | `MYCELIUM_WORKSPACE_ID` |
| MAS ID | `server.mas_id` | `MYCELIUM_MAS_ID` |
| Active room | `rooms.active` | `MYCELIUM_ACTIVE_ROOM` |
| Agent handle | `identity.name` | `MYCELIUM_AGENT_HANDLE` |

**Priority** (highest to lowest): env var → project config.toml → global config.toml → defaults

### Backend Settings (.env)

Stored in `~/.mycelium/.env`. Used by Docker Compose and the backend container.

| Variable | Description | Default |
|----------|-------------|---------|
| `LLM_MODEL` | LiteLLM model string | `anthropic/claude-sonnet-4-6` |
| `LLM_API_KEY` | Provider API key | (required for cloud LLMs) |
| `LLM_BASE_URL` | Custom LLM endpoint | (for Ollama, vLLM) |
| `DATABASE_URL` | PostgreSQL connection | (compose sets this) |
| `MYCELIUM_DATA_DIR` | Data directory | `~/.mycelium` |
| `MYCELIUM_DB_PASSWORD` | Database password | `password` |
| `MYCELIUM_BACKEND_PORT` | Backend port | `8000` |
| `MYCELIUM_DB_PORT` | Database port | `5432` |

### File Locations

| File | Purpose |
|------|---------|
| `~/.mycelium/config.toml` | CLI settings (identity, server URL) |
| `./.mycelium/config.toml` | Project settings (active room) |
| `~/.mycelium/.env` | Backend/Docker settings (LLM, database) |
| `~/.mycelium/rooms/{name}/` | Room memory files |

## Log Locations

```bash
mycelium logs                      # all services
mycelium logs mycelium-backend     # backend only
mycelium logs mycelium-db          # database only
docker logs mycelium-backend       # direct docker access
```

For CLI debug output:
```bash
mycelium --verbose status
```

## Reset Everything

When all else fails:
```bash
mycelium down --volumes   # stop and delete data
rm -rf ~/.mycelium        # remove all config
mycelium init             # fresh start
mycelium up
```

## Getting Help

1. Check `mycelium status` output
2. Review logs: `mycelium logs --tail 100`
3. Verify config: `cat ~/.mycelium/config.toml`
4. Check .env: `cat ~/.mycelium/.env`