Troubleshoot a WebDAV music library

Trace connection, authentication, path, proxy, and playback failures one layer at a time.

Updated

When you sit down to play an album and meet a connection error instead, the most frustrating part is rarely the fix itself—it is not knowing which knob to turn first. Changing the URL, root path, and account permissions all at once usually hides the real cause.

Every remote WebDAV session follows a simple four-step chain: Reach the server → Authenticate → Enumerate the directory → Stream the audio bytes. Walking that chain from left to right turns guesswork into a five-minute check.

[!NOTE] Reviewed in October 2026 for OFPlayer for Windows (26.0.6), OFPlayer for Android (26.0.2), and the web player (/app), using OpenList as the primary server example.

1. Read the HTTP status code first

Whenever a connection test returns an HTTP status code, your network route is working and the server is telling you which stage failed:

Symptom or status What the server is saying First thing to check
Timeout / Unreachable The request never reached the server process Container status, LAN IP, port mapping, host firewall
HTTP 401 Username or password was rejected Account spelling, recently reset password, saved credentials
HTTP 403 Account is valid, but lacks WebDAV access Enable WebDAV Read permission for that user in OpenList/AList
HTTP 404 The requested path does not exist Missing /dav prefix, or /music entered in both URL and root path
HTTP 405 WebDAV directory methods are not allowed here Admin web URL used instead of /dav/, or reverse proxy blocking PROPFIND

2. Layer 1: Cannot reach the server or connection times out

If Test connection spins and times out before returning any HTTP code:

  1. Test on your local network before debugging an external domain: Even if you use a custom domain, reverse proxy, or DDNS, test first on the same Wi-Fi using the server’s LAN address (such as http://192.168.1.100:5244/dav/music). If LAN works and the domain fails, the issue is in port forwarding, DNS, or the proxy—not your music mount.
  2. Confirm the container is running and listening:
    docker compose ps
docker compose logs --tail=50 openlist
  3. Check for network isolation: Guest Wi-Fi networks, router AP isolation, or a system-wide VPN/proxy on your PC or phone can block direct local-network traffic.

3. Layer 2: HTTP 401 or 403 login and permission errors

Being able to sign in to the web dashboard does not automatically mean the same account can read WebDAV:

  • HTTP 401 (Unauthorized): Re-enter the username and password in OFPlayer. If you need to reset the OpenList administrator password, run:
    docker exec -it openlist ./openlist admin set YOUR_NEW_PASSWORD
  • HTTP 403 (Forbidden): Open the server’s Manage → Users screen, edit the account used by OFPlayer, and confirm that WebDAV Read is enabled and its base path covers your /music mount.

4. Layer 3: Connected, but the list is empty or returns 404 / 405

When login succeeds but no songs appear—or you see HTTP 404 / 405—check how the path is assembled and how your proxy handles WebDAV methods.

Avoid duplicating /music

OFPlayer joins the Server URL (Endpoint) and the optional Root path field:

Configuration Server URL (Endpoint) Root path Resulting request & outcome
Mistake A http://192.168.1.100:5244 /music Missing /dav; hits the web UI and often fails with 405
Mistake B http://192.168.1.100:5244/dav/music /music Requests /dav/music/music; fails with 404 or an empty list
Correct 1 http://192.168.1.100:5244/dav /music Requests /dav/music cleanly
Correct 2 http://192.168.1.100:5244/dav/music (empty) Requests /dav/music cleanly

Verify container mounts and PROPFIND support

If the path is right and the list is still empty, check whether the OpenList web UI itself shows your audio files. If the web UI is also empty, inspect the Docker volume mapping (/path/to/music:/opt/openlist/music:ro) and verify that the container’s user UID/GID has read permission on the host directory.

If the web UI works over your domain but OFPlayer receives 405 Method Not Allowed, your reverse proxy or WAF may be blocking WebDAV’s PROPFIND method. Test it from a terminal:

curl -i -u username:password -X PROPFIND -H "Depth: 1" http://192.168.1.100:5244/dav/music

A working WebDAV endpoint responds with HTTP/1.1 207 Multi-Status and an XML directory listing.

5. Layer 4: Tracks appear, but clicking one fails or buffers

Seeing your songs in the list proves directory enumeration (PROPFIND) worked; clicking a track starts a separate media request (GET with Range headers):

  • Compare with a local file first: Play one known-good local MP3 or FLAC in OFPlayer to confirm your audio output device is working.
  • Redirected cloud-drive mounts: If OpenList is mounting a third-party cloud drive rather than a local disk or NAS, playback often relies on temporary 302 redirect URLs that may reject range requests or expire mid-session. Local or NAS disks remain the most reliable backing store.
  • Unsupported legacy formats: WebDAV streams original files without transcoding. FLAC, MP3, WAV, M4A/AAC, OGG, and Opus play natively; if you have older .wma or single-file .ape rips, convert or split them locally using the browser-based Audio Converter or CUE Splitter.
  • The 5,000-track cap on Windows: OFPlayer for Windows currently loads up to 5,000 tracks per remote list. For larger collections, split mounts by genre/era or use Navidrome.

6. Web player (/app) CORS and proxy routes

  1. Works on Windows and Android, fails in the web player (/app): Browser tabs enforce CORS (Access-Control-Allow-Origin) and block HTTPS pages from fetching plain http:// LAN addresses. Unless you configure HTTPS and CORS headers on your server, use the native OFPlayer for Windows or OFPlayer for Android apps.
  2. Slow startup or stuttering with proxies and VPNs: System proxies, VPNs, or router rules can detour local or streaming traffic. See the Network troubleshooting guide and Troubleshooting FAQ for step-by-step route checks.