Troubleshooting

Fix common problems fast

Ask ChatGPT Ask Claude.ai Open in Cursor

Solutions to the most common issues you'll encounter when building and deploying MUXI formations.

Installation Issues

Command Not Found

muxi: command not found

Solution:

Restart terminal
Check PATH includes install location
Reinstall: curl -fsSL https://muxi.org/install | bash

Permission Denied

Permission denied: /usr/local/bin/muxi

Solution:

Use sudo: curl ... | sudo bash
Or install to user directory: curl ... | bash (no sudo)

Server Issues

Server Won't Start

Error: bind: address already in use

Solution:

# Find what's using port
lsof -i :7890

# Kill it or change port
muxi-server --port 7891

Authentication Failed

Error: 401 Unauthorized

Solution:

Check key ID and secret match config
Verify timestamp is within 5 minutes
Regenerate keys: muxi-server init

Formation Issues

Missing Secrets

Error: Missing required secret: OPENAI_API_KEY

Solution:

muxi secrets setup
# Or
muxi secrets set OPENAI_API_KEY

Formation Won't Start

Error: Formation failed to start

Solution:

Check logs: muxi logs my-formation
Validate config: muxi deploy --validate
Check port availability

Invalid Configuration

Error: Invalid formation.afs

Solution:

Check YAML syntax
Validate: muxi deploy --validate
Compare with examples

Memory Issues

High Memory Usage

Formation using too much RAM.

Solution:

memory:
  buffer:
    size: 20  # Reduce from 50

Or restart:

muxi server restart my-assistant

Memory Not Persisting

Conversations not saved.

Solution:

memory:
  persistent:
    enabled: true
    provider: sqlite

Check database connection for PostgreSQL.

Tool Issues

MCP Tool Not Found

Error: MCP server not found

Solution:

# Verify server is installed
npx @anthropic/brave-search --version

# Check server name is correct

Tool Permission Denied

Error: Access denied to /etc/passwd

Solution: Configure allowed directories in your MCP file:

# mcp/filesystem.afs
schema: "1.0.0"
id: filesystem
type: command
command: npx
args:
  - "-y"
  - "@modelcontextprotocol/server-filesystem"
  - "/home/user/documents"

Network Issues

Connection Refused

Error: Connection refused to localhost:8001

Solution:

Check formation is running: muxi server list
Check port is correct
Start formation: muxi server start my-assistant

Timeout

Error: Request timeout

Solution:

Increase timeout in config
Check LLM API status
Simplify request

Deployment Issues

Deploy Failed

Error: Failed to deploy formation

Solution:

Check server is running
Verify profile credentials
Validate formation: muxi deploy --validate

Bundle Too Large

Error: Formation bundle exceeds limit

Solution:

Remove unnecessary files
Add to .muxiignore
Check knowledge directory size

Common Error Messages

`ECONNREFUSED` - Connection Refused

Full error:

Error: connect ECONNREFUSED 127.0.0.1:7890
    at TCPConnectWrap.afterConnect [as oncomplete]

Cause: MUXI Server isn't running

Solution:

# Start the server
muxi-server start

# Verify it's running
curl http://localhost:7890/health

`EADDRINUSE` - Port Already in Use

Full error:

Error: listen EADDRINUSE: address already in use :::7890
    at Server.setupListenHandle [as _listen2]

Cause: Another process is using port 7890

Solution:

# Find what's using the port
lsof -i :7890

# Kill it (if safe)
kill -9 <PID>

# Or use different port
muxi-server --port 7891

`401 Unauthorized` - Auth Failed

Full error:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key or signature"
  }
}

Cause: Invalid credentials or timestamp mismatch

Solution:

# Check your credentials
cat ~/.muxi/server/config.yaml

# Regenerate if needed
muxi-server init --reset

# Check system time is correct
date

`Missing required secret` - Secrets Not Set

Full error:

Error: Missing required secret: OPENAI_API_KEY
Required by: llm.api_keys.openai

Cause: Formation needs secrets that aren't set

Solution:

# Set the secret
muxi secrets set OPENAI_API_KEY sk-...

# Or run interactive setup
muxi secrets setup

`Formation validation failed` - Invalid YAML

Full error:

Error: Formation validation failed
  - agents[0].llm.model: required field missing
  - memory.buffer.size: must be integer, got string

Cause: Invalid formation.afs syntax

Solution:

Check YAML syntax (indentation, colons)
Validate: muxi deploy --validate
Compare with examples: docs/examples/

Common fixes:

# Wrong: String instead of integer
memory:
  buffer:
    size: "50"  # ✗ String

# Right:
memory:
  buffer:
    size: 50    # ✓ Integer

# Wrong: Missing colon
agents
  - name: assistant  # ✗ Missing colon after agents

# Right:
agents:              # ✓ Has colon
  - name: assistant

`Cannot find module` - MCP Server Not Installed

Full error:

Error: spawn npx ENOENT
Cannot find module '@modelcontextprotocol/server-brave-search'

Cause: MCP server package not installed

Solution:

# Install the package
npm install -g @modelcontextprotocol/server-brave-search

# Verify installation
npx @modelcontextprotocol/server-brave-search --version

# Check node/npm are installed
node --version
npm --version

`Tool execution failed` - MCP Tool Error

Full error:

{
  "error": {
    "type": "tool_error",
    "tool": "brave_web_search",
    "message": "HTTP 403: API key invalid"
  }
}

Cause: Invalid API key for MCP tool

Solution:

# Check secret is set
muxi secrets get BRAVE_SEARCH_API_KEY

# Set/update the secret
muxi secrets set BRAVE_SEARCH_API_KEY BSA...

# Restart formation
muxi server restart my-formation

`Memory database locked` - SQLite Lock

Full error:

Error: SQLITE_BUSY: database is locked

Cause: Another process is accessing the SQLite database

Solution:

# Stop all formations using this database
muxi server list
muxi server stop my-formation

# Check for stale lock files
rm data/memory.db-wal
rm data/memory.db-shm

# Restart formation
muxi server start my-formation

`Rate limit exceeded` - OpenAI Rate Limit

Full error:

{
  "error": {
    "type": "rate_limit_error",
    "message": "Rate limit reached for gpt-4 in organization org-..."
  }
}

Cause: Hit OpenAI API rate limit

Solution:

# Reduce parallel tasks
overlord:
  workflow:
    max_parallel_tasks: 2  # Was 10
    retry:
      initial_delay: 10    # Wait 10s between retries

# Or use cheaper model
llm:
  models:
    - text: "openai/gpt-4o-mini"  # Less expensive

`Webhook delivery failed` - Webhook Error

Full error:

Error: Failed to deliver webhook to https://your-app.com/callback
  Cause: getaddrinfo ENOTFOUND your-app.com

Cause: Webhook URL is unreachable

Solution:

Verify URL is accessible: curl https://your-app.com/callback
Check firewall/network settings
For localhost, use ngrok: ngrok http 3000
Update webhook URL in formation

`Python execution failed` - Artifact Error

Full error:

Error: Python artifact execution failed
  ModuleNotFoundError: No module named 'reportlab'

Cause: Required Python package not installed

Solution:

# Install the package
pip install reportlab

# Or install all recommended packages
pip install reportlab matplotlib pandas

# Check Python version
python --version  # Should be 3.8+

`Knowledge indexing failed` - Embedding Error

Full error:

Error: Failed to index knowledge base
  OpenAI API error: Incorrect API key provided

Cause: OpenAI key invalid or embedding API issue

Solution:

# Verify OpenAI key works
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

# Check embedding model is accessible
# (text-embedding-3-small is the default)

# Update API key if expired
muxi secrets set OPENAI_API_KEY sk-...

Getting Help

Still stuck? Here's how to get help:

Enable debug logging: yaml logging: level: debug

Then check: muxi logs --lines 200
Search existing issues: https://github.com/muxi-ai/muxi/issues
Ask the community: https://muxi.org/community
Report a bug: https://github.com/muxi-ai/muxi/issues/new

Include in your report:

MUXI version: muxi --version
OS and version: uname -a
Formation config (remove secrets!)
Full error message and stack trace
Steps to reproduce

We use cookies