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:

# 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:

export PATH="$HOME/.local/bin:$PATH"

2. Backend Not Running

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

Diagnosis:

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:

mycelium init

Or with custom API URL:

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:

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:

docker rm -f mycelium-db mycelium-backend mycelium-graph-viewer
mycelium up

6. Port Already in Use

Symptom: bind: address already in use

Diagnosis:

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:

LLM_MODEL=anthropic/claude-sonnet-4-6
LLM_API_KEY=sk-ant-...

Or for local Ollama:

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:

mycelium memory ls   # do memories exist?
ls ~/.mycelium/rooms/   # files present?

Fixes:

• Memories written directly (cat, editor) need reindex:

  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:

mycelium room ls           # list available rooms
mycelium room use my-project   # set active room

Or pass room explicitly:

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:

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. 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:

# 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:

# 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

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:

mycelium --verbose status

Reset Everything

When all else fails:

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