Troubleshooting
Start with two commands. They answer most questions.
docker compose psdocker compose logs --tail 100 staaash worker dbps shows which parts are running. logs shows the last lines each part wrote. Look for the word error.
I cannot open Staaash
Section titled “I cannot open Staaash”- Run
docker compose ps.staaash_server,staaash_workerandstaaash_postgresshould all be running. - Open
http://localhost:2113on the same computer. If that works, the problem is the network between you and the server: the server address, a firewall, or the proxy. - If you set
STAAASH_PORTin.env, use that port. - Behind a reverse proxy? Open the proxy address, not the port.
The database will not start, or Staaash keeps restarting
Section titled “The database will not start, or Staaash keeps restarting”DB_PASSWORDmust use letters and numbers only. A symbol or a space breaks the connection.- The database remembers the password from its first start. If you change
DB_PASSWORDin.envlater, the database keeps the old one, and Staaash cannot sign in to it. Put the old password back. - Read the last lines of
docker compose logs dbanddocker compose logs staaash.
Sign-in or uploads fail behind a proxy
Section titled “Sign-in or uploads fail behind a proxy”Staaash checks that the address in the browser matches the address it was called with. A proxy that changes the host, or two different addresses for the same drive, make requests fail on purpose.
- Use one address everywhere.
- Make sure the proxy passes on the original Host and says the visit was HTTPS.
- Compare against Reverse Proxy.
Share links have the wrong address
Section titled “Share links have the wrong address”Set STAAASH_PUBLIC_URL in .env to your public address, then run docker compose up -d. Links made after that use it. Links already sent keep their old address, so create a fresh share. See Configuration.
Previews are missing
Section titled “Previews are missing”Thumbnails and video previews come from the worker.
- Open admin Jobs. It must say at least one worker is online.
- If it says 0 online, run
docker compose logs workeranddocker compose up -d. - Open the Activity list and filter by Failed. A single broken video can fail without harming anything else.
The disk is full
Section titled “The disk is full”- Open admin Overview and Storage. They show who uses the space.
- Ask people to empty their trash. Trash is deleted for good after the cleanup time.
- Add space on the disk, or move to a bigger disk. To move the library, follow the steps in Configuration.
Big uploads slow down after a few minutes
Section titled “Big uploads slow down after a few minutes”Many low-cost SSDs write fast only until a small fast area inside them fills, often after a few GB to a few tens of GB. After that, each write waits while the drive tidies up, and uploads can drop to a few tens of MB/s. Reading stays fast. Staaash has the drive save each piece of an upload before it accepts the next one, so a crash never loses a piece it already confirmed, and these drives feel that most.
To check, watch the disk during a long upload, for example with iostat -x 2 on Linux or Task Manager on Windows. If the disk shows close to 100% busy while it writes only a little, the drive is the limit, not Staaash or your network. A drive that keeps its write speed fixes it: a regular hard drive (CMR, not SMR) or an SSD with its own memory chip (DRAM). Keeping the drive less full also helps.
An upload stopped halfway
Section titled “An upload stopped halfway”Unfinished uploads wait in a holding area and are cleaned up after a few hours. Try the upload again. If the same file keeps failing, check that the disk has space, and check the upload size limit under admin Settings, Uploads.
The admin Overview shows a problem
Section titled “The admin Overview shows a problem”| Line | What to do |
|---|---|
| Database | Check docker compose logs db. |
| Files volume | The files folder is not writable. Check that the disk is mounted and has space. |
| Worker | Check docker compose logs worker, then docker compose up -d. |
| Disk space | Free some space. |
| Restore check | Files on disk do not match the database. Run it again from Jobs after a restore. If it still complains, keep everything as it is and ask for help. |
A file says “Needs a storage check”
Section titled “A file says “Needs a storage check””A move, rename or delete stopped halfway, and Staaash kept every byte instead of guessing. See Storage Check.
Health checks for monitoring
Section titled “Health checks for monitoring”Two addresses answer without signing in, for tools like Uptime Kuma:
/api/health/liveanswers 200 while the web app runs. Docker’s health check uses it./api/health/readyanswers 200 when the database, the files folder and the worker are all fine. It answers 503 when one is not, when the last Restore check could not finish, or when a change needs a Storage Check. Its reply lists which check failed.
A failed preview job or another background job does not make ready fail. Those show in admin Jobs.
It broke after an update
Section titled “It broke after an update”- Check the logs for the first error.
- Check that
STAAASH_VERSIONin.envis the version you meant, and thatdocker-compose.ymlis from the same release. After an update from 1.x,Cannot find module '/app/dist/server/main.mjs'indocker compose logs staaashmeansSTAAASH_VERSIONstill names a 1.x version. - Restore your backup if you cannot fix it. See Updating and Backup and Restore.
Asking for help
Section titled “Asking for help”Ask in GitHub Discussions. For a bug, open an issue with the Bug report form. Include:
- what you did and what you expected
- the Staaash version from admin Overview
- the last lines of
docker compose logs
Do not paste passwords, your .env file, or private file names.