Navigation
On this page

Troubleshooting

Common issues and solutions when running Mediabox MCP -- containers, networking, permissions, and more.

This page covers common issues you may encounter when running Mediabox MCP and how to resolve them.

Containers Not Starting

Symptom: One or more containers fail to start or keep restarting.

Diagnosis:

docker compose ps
docker compose logs <service-name>

Common causes:

  • Docker not running — make sure the Docker daemon is active: docker info
  • Port already in use — another process is using the same port. Check with: 
    # Linux/macOS
lsof -i :8096
# Windows
netstat -ano | findstr :8096
    Stop the conflicting process or change the port in docker-compose.yml.
  • Insufficient memory — the full stack needs at least 2 GB of RAM (4 GB recommended). Check with docker stats.
  • Image pull failure — if you are behind a proxy or have limited internet, Docker may fail to pull images. Run docker compose pull to retry.

API Key Errors

Symptom: The MCP server cannot communicate with Jellyfin, Sonarr, or Radarr. Logs show “unauthorized” or empty responses.

Fix:

API keys are auto-generated by each service on first boot and extracted by the wizard into the .env file. If they are out of sync:

  1. Extract the current API keys from the service configs: 
    grep -oP '<ApiKey>\K[^<]+' config/sonarr/config.xml
grep -oP '<ApiKey>\K[^<]+' config/radarr/config.xml
  2. Update the .env file with the correct keys
  3. Recreate the MCP server to pick up the new environment: 
    docker compose up -d --force-recreate mcp-server

Port Conflicts

Symptom: Bind for 0.0.0.0:PORT failed: port is already allocated

Fix:

Another process or container is using the same port. Either stop the conflicting service or edit docker-compose.yml to remap the port:

ports:
  - "9096:8096"  # Map to a different host port

Then recreate:

docker compose up -d

Disk Space

Symptom: Downloads fail, Jellyfin cannot scan libraries, or containers crash unexpectedly.

Diagnosis:

# Check host disk space
df -h .

# Check Docker disk usage
docker system df

Fix:

  • Remove completed downloads from the ./downloads/ directory that have already been imported
  • Use the cleanup_server MCP tool to clear caches and orphaned torrents
  • Clean up Docker resources: docker system prune
  • Add more disk space or move the media directory to a larger drive

Permission Issues

Symptom: Services cannot read or write to the media directory. Logs show “permission denied” errors.

Fix:

The PUID and PGID values are set in the docker-compose.yml (auto-detected during wizard setup, typically 1000:1000). Ensure the host directories match:

# Check current ownership
ls -la ./media/ ./downloads/

# Fix permissions (adjust UID/GID to match docker-compose.yml values)
sudo chown -R 1000:1000 ./media/ ./downloads/ ./config/
sudo chmod -R 755 ./media/ ./downloads/

Cloudflare Tunnel Not Connecting

Symptom: The cloudflared container is running but services are not accessible via their subdomains.

Diagnosis:

docker logs cloudflared

Common causes:

  • Invalid tunnel token — verify CLOUDFLARE_TUNNEL_TOKEN in your .env file matches the token from the Zero Trust dashboard
  • Tunnel deleted — if the tunnel was deleted in the Zero Trust dashboard, create a new one and update the token
  • DNS not managed by Cloudflare — the domain must use Cloudflare’s nameservers
  • Public hostnames not configured — check that each service has a public hostname entry in the Zero Trust dashboard under your tunnel

Prowlarr Indexer Failures

Symptom: Prowlarr shows indexers as failed or returns no search results.

Diagnosis:

docker logs prowlarr

Common causes:

  • No indexers added — Prowlarr starts with no indexers. You must add them manually after setup (see Quick Start)
  • FlareSolverr not tagged — indexers that require Cloudflare bypass need the flaresolverr tag. Create the tag and assign it to both the FlareSolverr proxy and the relevant indexers
  • Indexer is down — some indexers have intermittent availability. Test manually in Prowlarr’s UI
  • Rate limiting — you may be hitting the indexer’s request rate limit. Wait and try again
  • Invalid credentials — if the indexer requires a login, verify your credentials in the indexer settings

MCP Server Not Responding

Symptom: Claude Desktop or other clients cannot connect to the MCP endpoint.

Diagnosis:

docker logs mcp-server
curl http://localhost:3000/health

Common causes:

  • Container not running — check with docker compose ps. Look for the mcp-server container
  • Wrong URL — ensure the client is configured with the correct URL including the /mcp path (e.g., http://localhost:3000/mcp)
  • Missing API keys — if JELLYFIN_API_KEY, SONARR_API_KEY, or RADARR_API_KEY are empty in .env, the server starts but tools will fail. Extract and set the keys
  • OAuth2 token expired — access tokens expire after 24 hours. MCP clients should handle refresh automatically, but restarting the MCP server clears all tokens (in-memory store), requiring re-authentication
  • Firewall blocking — on VPS deployments, ensure port 443 (Caddy) or 3000 (local) is open

Telegram Bot Not Working

Symptom: The Telegram bot doesn’t respond to messages.

Common causes:

  • Container not in stack — the bot is only added to docker-compose.yml if enabled during the wizard. Check with docker compose ps for telegram-bot
  • Invalid bot token — verify TELEGRAM_BOT_TOKEN in .env. Test with: curl https://api.telegram.org/bot<TOKEN>/getMe
  • User not allowed — if ALLOWED_TELEGRAM_USERS is set, your Telegram user ID must be in the list
  • LLM API key invalid — check OPENROUTER_API_KEY or GOOGLE_AI_API_KEY in .env
  • MCP server unreachable — the bot connects to http://mcp-server:3000/mcp internally. Ensure the MCP server is running

Getting More Help

If your issue is not listed here:

  1. Check the full container logs: docker compose logs
  2. Search the GitHub Issues for similar problems
  3. Open a new issue with your logs and environment details