Troubleshooting

Troubleshooting Guide

This page reflects the current desktop/mobile architecture in v0.1.41.

Before You Debug

Start by deciding which surface is actually failing:

  • desktop hub
  • mobile companion
  • remote route
  • buyer/download/license flow

Connectivity

Mobile or remote client gets 401 Unauthorized

This usually means the client is trying to use protected /api/* routes without a valid bearer token.

What to do:

  1. Re-open the latest desktop QR instead of reusing an old remote URL.
  2. If the desktop shows pairing_not_armed, arm pairing again before reconnecting.
  3. On mobile, disconnect and reconnect so the app can pair again or refresh auth state.

Remote playback fails with a license-related message

This is different from a normal network error.

What to check:

  1. The desktop hub has an active license state for remote access.
  2. The hub can still validate or reuse its signed entitlement state.
  3. You are not testing remote while expecting LAN-only behavior.

QR returns 409 pairing_not_armed

This is expected when a remote route exists but the desktop has not armed pairing yet.

What to do:

  1. Open the desktop app locally.
  2. Arm pairing from the remote/connect settings flow.
  3. Refresh the QR and rescan it.

Pairing share link opens the browser but not the app

Pairing share links are HTTPS links that hand off to the app.

What to check:

  1. Open the link on the phone where Music Hub is installed.
  2. Tap Open in Music Hub on the landing page.
  3. If the button is disabled, ask the hub owner for a fresh pairing link.
  4. If the app is not installed, install it first and reopen the same link.

The landing page is only a handoff page. The desktop hub still validates the pairing code when the app connects.

Files or /api/browse returns 401, 403, or Forbidden

The folder browser is a protected route for remote callers.

What to do:

  1. Make sure the client is paired and has a fresh bearer token.
  2. Reconnect from the QR if the auth state is stale.
  3. Confirm the folder still exists on disk.

If the phone was already paired and public web access is set to Shared pages only, /api/browse should still work for that paired phone. A new 403 there usually means the mobile private-access path regressed, not that the remote route itself is missing.

Mobile cannot reach the hub locally

What to check:

  1. The desktop hub is running on 38472.
  2. Both devices are on the same network if you are not using Cloudflare or Tailscale.
  3. The desktop host is reachable at YOUR_IP:38472.
  4. Firewall rules are not blocking the app.

For Docker, also make sure the QR advertises the host's LAN address instead of localhost. Docker Desktop and custom port mappings may need MUSIC_HUB_ADVERTISE_HOST and MUSIC_HUB_ADVERTISE_PORT; see Docker Setup.

Helpful local checks:

curl http://localhost:38472/api/ping
lsof -i :38472

Database health

Desktop opens but library/settings look unavailable

The hub may be in degraded mode because the DB is faulted or incompatible.

Check:

curl http://localhost:38472/api/info
curl http://localhost:38472/api/settings

Look for databaseHealth.status.

Recover a faulted DB

Use the local rebuild flow instead of deleting the DB by hand.

curl -X POST http://localhost:38472/api/database/rebuild

Notes:

  • this route is local-only
  • the old DB is preserved and archived before replacement
  • a full rescan may start automatically afterwards

Database path and logs

Current default locations:

  • DB: ~/.music-hub/music.db
  • Config: ~/.music-hub/config.json
  • Electron log: ~/.music-hub/electron.log

Playback

Public share page loads but playback fails

Public share pages depend on bootstrap + signed media sessions.

What to check:

  1. The share bootstrap endpoint returns 200.
  2. Reloading the same link in the same browser tab should reuse the same shareSessionId instead of creating a new one.
  3. The share page is still renewing shareSessionId with /api/share/session/heartbeat.
  4. The media request includes the latest mediaToken.

If too many interactive share sessions are active at once for the same page, the server can return 429. Preview bots from WhatsApp, Telegram, Discord, etc. should appear in session telemetry but should not consume that interactive limit.

Collaborative playlist track does not play

Collaborative playlist playback goes through your own hub.

What to check:

  1. Your phone or desktop is connected to your personal hub.
  2. Your personal hub is still a member of that collaborative playlist.
  3. The source hub is online and reachable.
  4. The source hub has not revoked your hub.
  5. The track has not been removed from the shared playlist.

If playback worked once and then fails while the source hub is offline, wait until the source hub is reachable again or import the track into your own hub when that option is available.

Notes appear in the wrong place

Music Hub has two note contexts:

  • Track notes belong to the track globally.
  • Playlist track notes belong to that track inside one playlist.

If you expected a note to appear everywhere, add it from the track detail page. If you want the note to be playlist-specific, add it from the playlist track context.

Playback is slow or stutters

What to check:

  1. Prefer a strong Wi-Fi signal or a closer route to the hub.
  2. If remote, confirm the client is not repeatedly falling back after direct-stream failures.
  3. Restart the current playback session if a stale connection mode was cached.

Remote access

Web session bootstrap failed (403) in the browser (full hub, not /share/)

That message comes from the desktop UI calling POST /api/auth/web-session before protected API calls when the page is loaded on a non-localhost hostname (for example your Cloudflare URL).

Checklist:

  1. allowRemoteOpenAccess in config — After toggling Public remote URI in Advanced, confirm ~/.music-hub/config.json has "allowRemoteOpenAccess": true. If it stays false, the setting did not save (wrong hub process, or the request failed).

  2. License / remote entitlement — If the hub is not remoteLicensed, the server returns 403 with code: license_required_for_remote (not browser_access_disabled). Fix license/validation first.

  3. Same machine behind the tunnel — The browser must hit the same desktop instance that you configured.

  4. Proxy headers — The hub classifies traffic using forwarded client IP headers (cf-connecting-ip, x-forwarded-for, etc.). If your edge strips them, anonymous browser access rules may not apply as expected.

Public /share/... pages use a separate path: they should load shared content without opening the full hub and without requiring Public remote URI (see share bootstrap in the API docs). If only share pages fail, check the share bootstrap response and license, not only web-session.

Cloudflare/Tailscale route exists but app still cannot browse library

Remote networking alone is not enough anymore. The client still needs auth.

What to check:

  1. Pair/refresh flow succeeded.
  2. The remote client is sending Authorization: Bearer ....
  3. You are not trying to call a local-only endpoint remotely.

Phone was paired on Wi-Fi, Wi-Fi is now off, and covers/search/playback all die together

That path should now work without a re-pair if the phone was already paired once.

What to check:

  1. The phone is using the latest saved hub config or link from desktop.
  2. The paired bearer can still reach /api/media/session, /api/search, and /api/browse.
  3. The desktop remote scope is only limiting public web access, not the phone's private session.
  4. The mobile diagnostics log does not show repeated Protected request failed or Remote media session failed.

Share page assets fail behind a custom proxy

Music Hub expects the share page and its static assets to load same-origin, while API CORS stays narrow.

If you front the app with your own proxy:

  1. Pass /share/* and static assets through without rewriting them into API requests.
  2. Do not force unknown origins to throw inside API CORS handling.

Mobile iOS shipping

EAS prompts to run git init even though mobile/ is already a git repo

This often happens when Git refuses the repository with dubious ownership (the folder is owned by a different user UID than the account running the build). EAS then assumes there is no usable git metadata.

What to do:

  1. Prefer fixing ownership: sudo chown -R "$(whoami)" /path/to/mobile (adjust path).
  2. Or allow the path explicitly: git config --global --add safe.directory "/absolute/path/to/mobile".
  3. Re-run npm run build:final from mobile/.

The mobile build scripts also attempt to register safe.directory automatically before invoking EAS when they detect this pattern.

Packaging and startup

macOS app is blocked on first open

Because the app is still in beta distribution:

  1. Right-click the app and choose Open.
  2. If macOS blocks it, allow it in Privacy & Security.

Splash screen stays visible too long

Check the Electron log first:

tail -f ~/.music-hub/electron.log

If the backend is healthy but the UI is not loading, also test:

curl http://localhost:38472/api/ping
curl http://localhost:38472/api/settings

Buyer / Recovery Flow

I paid, but I lost the original email

Use the current recovery path exposed from the landing flow instead of expecting a permanent raw DMG URL.

The download link expired

That is expected for the current secure download flow. Use the recovery flow to generate a fresh short-lived download link.

Diagnostics and Support

The app is crashing or misbehaving and I want to send logs

The desktop hub includes a diagnostics suite (shipped in v0.1.41+):

  • Log locations: macOS ~/Library/Logs/Music Hub/ (main.log for Electron shell, desktop.log for hub process)
  • Config and DB: ~/.music-hub/config.json and ~/.music-hub/music.db
  • Opt-in upload: In Settings, enable Send diagnostics to automatically upload logs for support triage
  • Crash reports: When the app crashes, you will be prompted to send a report — this works even if the opt-in toggle is off
  • What is not uploaded: Your music files, database, or personal secrets are never included

How to manually collect diagnostics

# Check hub health
curl http://localhost:38472/api/ping
curl http://localhost:38472/api/info
 
# Check logs on macOS
tail -f ~/Library/Logs/Music\ Hub/desktop.log
 
# Check logs on the old path (pre-v0.1.41)
tail -f ~/.music-hub/electron.log
Building from SourceAPI Reference