How to Debug Issues with Music Assistant Server: A Complete Troubleshooting Guide

Enable verbose logging with --log-level verbose, monitor the log file at ~/.musicassistant/musicassistant.log, and inspect the core MusicAssistant class via Python REPL to isolate startup, networking, or provider failures in your Music Assistant server instance.

Debugging the Music Assistant server requires understanding its asynchronous architecture built around the core MusicAssistant class and aiohttp-based web layer. Whether you are troubleshooting port binding errors, SSL certificate failures, or provider loading issues, the music-assistant/server repository provides comprehensive logging and diagnostic hooks. This guide walks through systematic debugging techniques using actual source file paths and runnable code examples from the codebase.

Locate and Monitor Log Files

Music Assistant writes runtime logs to a rotating file in your user data directory. According to the source in music_assistant/__main__.py (lines 110-120), the setup_logger() function initializes a RotatingFileHandler that persists logs to ~/.musicassistant/musicassistant.log.

The same file also configures console output (STDOUT/STDERR) with a ColoredFormatter for readable terminal output (lines 84-104).

To monitor logs in real-time:

tail -f ~/.musicassistant/musicassistant.log

If the log file does not exist, the server failed before logger initialization—usually indicating a Python import error or missing dependency.

Enable Verbose Logging for Detailed Diagnostics

The server defines a custom VERBOSE log level (numeric value from constants.VERBOSE_LOG_LEVEL) that captures detailed diagnostic information beyond standard INFO levels.

To enable verbose logging, start the server with:

python -m music_assistant --log-level verbose

Alternatively, set the environment variable:

export LOG_LEVEL=verbose
python -m music_assistant

The --log-level argument is parsed in __main__.py (lines 65-70) and passed to setup_logger() before the event loop starts.

Diagnose Common Startup Failures

Port Binding Errors

If you see the error "Could not bind to 0.0.0.0, will start on all interfaces" in your logs, the server cannot attach to the specified network interface. This occurs in music_assistant/helpers/webserver.py (lines 107-110) when the TCPSite fails to start.

Verify the port is available:

lsof -i :8095

# or start with alternative binding

python -m music_assistant --bind-ip 127.0.0.1 --bind-port 8080

Import Errors and Missing Dependencies

An ImportError: cannot import name 'Webserver' typically indicates a broken virtual environment or missing aiohttp dependency. The scripts/setup.sh file contains the exact pip install -r requirements.txt command used to establish a clean environment.

Provider Loading Failures

During startup, MusicAssistant.__load_provider_manifests() (called from MusicAssistant.start() in music_assistant/mass.py) iterates over provider directories and logs parsing errors at ERROR level. Search your logs for provider or manifest to identify invalid JSON or missing dependencies in music_assistant/providers/<name>/manifest.json.

Inspect Runtime State via Python REPL

You can introspect a running or temporary instance by instantiating the MusicAssistant class directly from music_assistant/mass.py (lines 10-30). This is useful for verifying controller initialization and provider registration.

import asyncio
from music_assistant import MusicAssistant

async def dump_state():
    ma = MusicAssistant(
        storage_path="~/.musicassistant",
        cache_path="~/.musicassistant/.cache"
    )
    await ma.start()
    print("Version:", ma.version)
    print("Loaded providers:", list(ma.providers.keys()))
    print("Webserver URL:", ma.webserver.base_url)
    await ma.stop()

asyncio.run(dump_state())

The webserver attribute is an instance of WebserverController (defined in music_assistant/controllers/webserver/controller.py, lines 99-106), which wraps the low-level aiohttp implementation.

Debug the HTTP API and WebSocket Layer

Verify the server is responsive by checking the health endpoint:

curl -s http://localhost:8095/api/health | jq .

A JSON response with "status":"ok" confirms the aiohttp server in music_assistant/helpers/webserver.py is accepting connections.

To trace individual requests, temporarily add middleware logging in helpers/webserver.py:

async def _log_request(request, handler):
    request.app.logger.debug("Request: %s %s", request.method, request.path)
    return await handler(request)

# Inside Webserver.setup, before route registration:

self._webapp.middlewares.append(_log_request)

Troubleshoot SSL and Certificate Verification

SSL verification is handled by verify_ssl_certificate() in music_assistant/controllers/webserver/helpers/ssl.py. When you trigger the Verify SSL action in the UI, WebserverController.get_config_entries() (lines 135-142) calls this helper and returns a dataclass with fields valid, subject, issuer, and expiration.

The result is logged at INFO level and displayed as a toast notification. For additional detail, temporarily add debug logging in helpers/ssl.py:

self.logger.debug("SSL cert info: %s", cert_info)

Diagnose Provider Configuration Problems

Each provider resides under music_assistant/providers/<name>/ with a manifest.json describing required configuration. To test dynamic loading:

from music_assistant.helpers.util import load_provider_module
module = load_provider_module("spotify")  # example provider name

print(dir(module))

If the module raises an exception, the stack trace appears in the log with the prefix Provider load error:.

Capture Minimal Reproduction Cases

When reporting issues, include these elements to expedite resolution:

1. Exact command line used to start MA (including environment variables)
2. Relevant log excerpt using grep -C 5 "<error-keyword>" ~/.musicassistant/musicassistant.log
3. Steps to reproduce (e.g., "open /api/player/play after enabling SSL")
4. Python version (python -VV) and OS (uname -a)
5. Minimal reproduction script (such as the REPL snippet above)

Summary

• Monitor the rotating log file at ~/.musicassistant/musicassistant.log to catch startup errors configured in music_assistant/__main__.py
• Use --log-level verbose or set LOG_LEVEL=verbose to enable detailed diagnostic output from the custom log level
• Check music_assistant/helpers/webserver.py for port binding issues and scripts/setup.sh for dependency verification
• Inspect runtime state by instantiating the MusicAssistant class from music_assistant/mass.py in a Python REPL
• Verify SSL certificates using the verify_ssl_certificate function in music_assistant/controllers/webserver/helpers/ssl.py
• Examine provider manifests in music_assistant/providers/<name>/ and check __load_provider_manifests() logs to debug loading failures

Frequently Asked Questions

How do I enable debug logging in Music Assistant server?

Enable debug logging by starting the server with python -m music_assistant --log-level verbose or setting the environment variable export LOG_LEVEL=verbose before execution. This activates the custom VERBOSE log level defined in the constants module and is parsed in music_assistant/__main__.py before the logger initializes.

Where does Music Assistant store its log files?

Music Assistant writes runtime logs to ~/.musicassistant/musicassistant.log using a RotatingFileHandler configured in music_assistant/__main__.py (lines 110-120). If this file does not exist, the server likely failed before logger initialization, usually due to a Python import error or missing dependency.

Why is Music Assistant failing to start on port 8095?

Port binding failures occur when the address is already in use or the process lacks sufficient privileges. Check music_assistant/helpers/webserver.py lines 107-110 for the error message "Could not bind to 0.0.0.0", and verify no other process is using the port with lsof -i :8095 or start with --bind-port to specify an alternative.

How can I verify my SSL certificate configuration?

Use the Verify SSL action in the UI or CLI, which triggers verify_ssl_certificate() in music_assistant/controllers/webserver/helpers/ssl.py (called from WebserverController.get_config_entries() at lines 135-142). The function returns a dataclass with valid, subject, issuer, and expiration fields, which are logged at INFO level and displayed in the interface.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}