Navidrome Subsonic API Issues — Complete Guide

In this tutorial, you'll learn about Navidrome Subsonic API Issues. We cover key concepts, practical examples, and best practices.

Hook

You configure Sonixd, DSub, or Subtracks to connect to your Navidrome server using the Subsonic API. The client says "Connection failed" or "Invalid credentials." Your Navidrome web UI works perfectly, but every Subsonic client refuses to talk to it.

The Wrong Way

Creating a new admin user in Navidrome and using those credentials for the Subsonic client does not help — if the authentication method is wrong, it fails for all users.

# BAD: Creating yet another user
navidrome admin adduser newuser newpassword

User created: newuser
Subsonic client: "Connection failed" — still broken

The issue is never which user you use; it is how the credentials are transmitted.

The Right Way

Subsonic clients use HTTP basic auth or token-based auth (Salt + Token). Navidrome enforces token-based auth for Subsonic API.

# 1. Get your Navidrome password hash (base64 of "username:password")
echo -n "admin:mypassword" | base64

YWRtaW46bXlwYXNzd29yZA==

# 2. Test Subsonic API directly
curl -s "http://localhost:4533/rest/ping?u=admin&p=enc:mypassword&c=myapp&f=json" | jq .

{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1"
  }
}

If the ping works, the client configuration is the problem. In the client:

• Server: http://your-server:4533 (or https://your-server behind reverse proxy)
• Username: Navidrome username
• Password: Your Navidrome password (plain text, client handles encryption)
• App name: Anything unique

# 3. Enable plain-text password authentication if the client is old
# In navidrome.toml:
# EnableTokenAuth = false
# Then restart — only if the client does not support token auth

Prevention

• Use modern Subsonic clients (Sonixd, Subtracks, Symfonium) that support token auth.
• Do not expose Navidrome directly to the internet — use a reverse proxy with HTTPS.
• Keep Navidrome updated — Subsonic API compatibility improves with each release.
• Test with curl before configuring any client.
• Set a unique App name per client to help debug auth issues.

Advanced Troubleshooting

Check the Logs

Most TOOL errors are logged to stdout or a dedicated log file. Check your logs first:

# Check system logs
journalctl -u tool --since "1 hour ago"

# Or check the application log
tail -50 ~/.tool/logs/error.log

Test with a Minimal Example

Create the simplest possible tool configuration to verify the base setup works:

tool --version
tool --help

If the minimal test passes, add configuration options one at a time until you find the breaking change.

Common Configuration Mistakes

• Using the wrong file path or URL in configuration
• Forgetting to restart TOOL after changing config files
• Mixing tabs and spaces in YAML configuration files
• Setting incorrect permissions on configuration directories

When to Reinstall

If none of the above resolves the issue, consider a clean reinstall:

# Backup your configuration
cp -r ~/.tool ~/.tool.bak

# Remove and reinstall
# Follow the official TOOL installation guide

This ensures you start from a known good state and can isolate the issue.

Common Mistakes with subsonic api

1. Using head and tail instead of pattern matching, causing runtime errors on empty lists
2. Forgetting that lazy evaluation defers computation until the value is forced, causing space leaks with unevaluated thunks
3. Using return to exit a function early instead of wrapping a pure value in the monad

These mistakes appear frequently in real-world NAVIDROME code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ

DodaTech — connect any Subsonic client, every time.