Troubleshooting

Organised by what you see. Most of these symptoms were real reports, and each entry says what was behind it and what to check - starting with the cheap checks, because the usual cause is a network setting, not SoundStorm.

A phone or TV cannot reach it

The computer itself opens http://localhost:8099, but another device does not.

1. Use the computer's address, not localhost. On a phone, localhost is the phone. Settings → Use on your phone or TV shows the right address, for example http://192.168.1.50:8099. Include the port.
2. Same network? A guest Wi-Fi network usually cannot see other devices, and mobile data is not the home network at all. The installer cannot check either of these.
3. Windows: is the network Public? Windows makes every new Wi-Fi network Public, and Public lets nothing in. Run Update SoundStorm while on the home network: it notices, asks whether this is your home network, and with your consent marks it Private and opens SoundStorm's port for private networks only.
4. Windows: a Docker firewall block. If the firewall alert for "Docker Desktop Backend" was cancelled during setup, Windows added a Block rule, and Block beats Allow. The same update step removes the block for private networks.
5. Did the computer's address change? A laptop that moves, or a router that hands out a new address, breaks the secure name. The installer updates it on every launch on Windows; elsewhere update SOUNDSTORM_TLS_HOSTS in .env. Giving the computer a fixed address in the router (a DHCP reservation) prevents it.

Certificate warnings

In the default (auto) mode there should be none. The secure https://<id>.home.soundstorm.dev:8099 name carries a real Let's Encrypt certificate. If you see a warning:

• You typed https:// with an IP address. A trusted certificate is for the name, not the address. Use http:// with the IP, and the page moves to the secure name by itself once it has checked it can reach it.
• The page never moves to the secure name. Some routers refuse to resolve a public name that points at a private address (DNS rebinding protection). SoundStorm then stays on plain http rather than redirect into a failure. Allowing soundstorm.dev in the router's rebinding settings, or using a different DNS server, fixes it.
• Self-signed mode (SOUNDSTORM_TLS=self-signed) warns on every device until https://<server>:8099/ca.crt is installed on it. That is expected.
• A warning after a reinstall in self-signed mode: a browser pins a clicked-through exception to one exact certificate, and a reinstall makes a new one. Click through once more.

The service worker never answers a page load, precisely so that a changed certificate shows the browser's own warning rather than a cached page that cannot work. A browser still holding a very old version of the worker can be stuck until its site data is cleared.

Android will not offer "Install app"

Chrome only installs a web app from an origin with a trusted certificate - not from a LAN IP address, and not from a self-signed certificate even after clicking through the warning. Open the secure .home.soundstorm.dev address and install from there, or use the Android app.

A shelf stuck on "Getting ready"

SoundStorm sets up each media server itself in the background, retrying with backoff, and the setup box shows each shelf's state. The media servers take from seconds to a minute or more to start - the photo server's models and the films server are the slowest - so "Getting ready" for the first few minutes is normal.

• Still waiting after several minutes: check that the container is running and healthy (docker compose ps) and look at SoundStorm's log, which says what it is waiting for. The owner also sees the raw error, folded under Details, on a failed shelf.
• A shelf that says its credentials do not work: this happens when a media server's data and SoundStorm's data got out of step - one volume wiped and not the other - so the server has an account whose password nobody holds. SoundStorm says so rather than retrying for ever, because the fix is a human decision: restore a backup (see Backup and restore), or reset the media server's volume and let it be set up afresh.
• A temporary error is not a password problem. Only a 401 or 403 is taken to mean wrong credentials; a busy server, a timeout or a refused connection just means wait. A media server that is loading often accepts the connection and answers "unavailable" for a while.
• A setup interrupted half way - a timeout, the media server restarting - finishes on the next attempt by itself: the passwords it made are kept from the moment they were made.

Files do not appear

• Dropped onto the window: SoundStorm asks the right media server to look at once, two seconds after the last file of a drop, and an uploaded file is normally searchable within about five seconds. If a file was skipped, the drop panel says why: already in your library, a format that shelf does not take, or no shelf it could name.
• Copied into the folders by hand: each media server finds new files on its own timer, every minute or two. Settings → Check for new files asks them all now.
• "Indexing new files..." under the filters means a media server is still working through what arrived. An empty search during that is not a fault.
• Music filed under a strange artist: the artist comes from the file's tags. A file with no tags lands under the folder above it, or Unknown Author when that folder is a container like Music or Downloads - somewhere obvious to find and fix.
• A shelf you cannot see at all: the owner can tick which shelves each person sees. A hidden shelf disappears from tabs, search and uploads.
• Only EPUBs and PDFs are read on the ebook shelf; other book formats are ignored.

Deleted items still show

This was a real report - "I deleted all the files but some still show" - and it had a different cause for each media server:

• Films and TV, after emptying a folder by hand: the films server refuses to remove anything when a library folder comes back completely empty, because it cannot tell "everything was deleted" from "the drive did not mount". SoundStorm keeps a small README.txt in every shelf so it is never empty, and writes it back before every scan. Do not delete it; if you did, Check for new files puts it back and the old entries go within seconds.
• Audiobooks: the audiobook server keeps serving books whose files are missing (so a book on an unplugged drive keeps its listening position). SoundStorm filters them out itself.
• Deleted from inside the app: items go to a bin for 30 days and leave every shelf at once; Undo brings them back.

Music is slow to start away from home

Usually the home's upload speed. Things that already happen automatically: songs are sent without the cover art inside them (which made browsers wait for megabytes), sending is paced so a skip does not wait behind a backlog, and a slow connection is measured as the app opens and songs start at 128 kbps - going back to full quality by itself once the connection is fast again.

• Settings → Playback on this device: "Original, lower on a slow connection" is the default. "Always original" turns off every fallback - only choose it on a fast connection.
• A ring round the play button means the song is waiting on the network, not stuck.
• Films default to the original at home and 20 Mbit away; the player's Quality picker can go lower for the sitting.
• Downloads play from the device and need no connection at all.

Remote access says it cannot work

• "Carrier-grade NAT": the internet provider shares one public address between many homes, so no port forward can ever reach the house. Use Tailscale instead.
• "Double NAT": the router is behind another router, often the provider's box. A forward is needed on both, or put the provider's box in bridge mode.
• "The port is not open yet": the router did not accept an automatic mapping. Forward the port shown to the computer shown, by hand, in the router's settings; the panel notices when it starts working.

More on Away from home.

Photo backup messages

The Android app's photo backup shows why it stopped in Settings → Your photos, and the message is meant to say what to do:

Android decides when backup jobs run, so a large backup proceeds in stretches, especially with "only while charging" on. Photos already on the server are never sent twice, even after a reinstall.

Locked out

• Sign-in makes you wait after several wrong passwords, doubling up to a few minutes. A device that has signed in successfully before is judged on its own record, so somebody else guessing never holds it up.
• Forgotten password: the owner can reset anybody else's in People. For the owner's own, see A forgotten password.
• Sign-up asks for a setup code: it is in the setup window's last screen, in .env in the install folder (SOUNDSTORM_SETUP_CODE), or, for a compose-only install, in the log.
• "Waiting for approval" after the right password: the owner has turned on approval of new devices. Allow it from another device signed in to the same account, or the owner's; with nothing else signed in, the setup code from .env allows it. A request is forgotten after ten minutes.
• "Choose a new password" before anything else works: the owner asked everyone for one, or the old password no longer meets the rules (12 characters, not a common one).
• A PIN that keeps failing on a shared device: after five wrong tries switching to that person waits, and after fifteen they are taken off the device - sign in with the password instead.