An app keeps restarting or shows "unhealthy" — how to find out why
· Updated 18 September 2026 · SparkBox team
The checkup says something like "sb-immich-server is stuck in a crash-restart loop (14 restarts so far)" or "sb-npm is running, but its health check is failing". The app is not broken at random. It is telling you the reason in its own log, usually in the last twenty lines, and there are only four reasons it is ever likely to be.
The 10-second version: Don't press Restart — it is already restarting. Open the app's log (Apps → the app → Logs, or ask Tom AI "why does X keep restarting?"), read the last lines, and match them to one of the four causes below. Never use Clean Slate for this; it deletes the app's data and the loop was not about data.
1. What the three words mean
- Crash-looping — the app starts, hits a problem, exits, and Docker starts it again. You will see the restart count climbing. It cannot be used until the problem is fixed.
- Unhealthy — the app is running, but its own health check (a small "are you okay?" request Docker sends it every few seconds) is failing. It may half-work: the page loads but logins fail, or searches hang.
- Never started — the container exists but never ran once. Something it needed at the exact moment of starting was missing.
2. Read the log — that is the whole method
- Dashboard → Apps → find the app → Logs. Scroll to the bottom. The last error before the restart is the one that matters; everything above it is the same story repeating.
- Or from the box:
sudo sparkbox logs <app>(for examplesudo sparkbox logs immich). - Or just ask Tom AI: "why does Immich keep restarting?" — it reads the log itself and names the cause.
Now match what you see to a cause.
3. The four causes, and what to do
Cause 1 — the app's database is rejecting its password
Log says things like password authentication failed, 28P01, Access denied for user. This follows a restore, a regenerated .env, or a reset. The app is fine; its saved login no longer matches the database's. SparkBox has a safe repair that takes a fresh database dump first and then rotates only the login:
sudo sparkbox repair-db-auth <app> # e.g. immich, nextcloud, paperless
sudo sparkbox repair-immich-db-auth # Immich has its ownThe checkup prints exactly this command when it detects the case. Full story for Immich: Immich stuck on Postgres error 28P01.
Cause 2 — a port it needs is already taken
Log says address already in use or bind: permission denied. Something else on the box owns that port — often a leftover container from before SparkBox, or the NAS's own web server on 80/443. Fix: Port already in use.
Cause 3 — it cannot write to its folder
Log says permission denied, read-only file system, EACCES. The app runs as a specific user (set by PUID/PGID) and the folder belongs to someone else — usually after moving data to a new drive or copying it in as root. Fix: Permission denied / PUID and PGID.
Cause 4 — the disk is full, or the app ran out of memory
Log says no space left on device, or it ends abruptly with Killed / exit code 137. Free space is on the dashboard's Overview; a full system drive stops many apps at once. Fix: Disk is full. For memory, the NAS or VPS is simply too small for that app — Immich's machine-learning and Frigate are the usual ones; turn the heavy option off in that app's settings or run it on a bigger box.
If it is "unhealthy" but the log looks clean
Two known SparkBox-specific cases: Gotify and a few minimal images had a health check that used a tool the image doesn't ship (fixed in the app pack — Update your box), and apps behind the VPN look unhealthy for a minute or two while the tunnel reconnects (VPN container unhealthy). If the app actually works when you open it, it is the second one — wait it out.
4. After the fix
You do not need to restart anything by hand: once the cause is gone, the next automatic restart succeeds and the loop ends within a minute. Run the checkup again (Tom AI: "run a checkup") to confirm it has cleared.
Frequently asked
What is the difference between crash-looping, unhealthy, and never started?
Crash-looping: starts, dies, restarts, repeat. Unhealthy: running but failing its own health check. Never started: created but never ran, because something it needed was missing at that moment.
Will restarting fix it?
Almost never — it is already being restarted automatically. The last log lines name the reason; fix that and the loop stops on its own.
Is my data gone?
No. A restart loop does not touch the app's files under /opt/sparkbox/modules/<app>/config. Do not use Clean Slate to fix a loop — that does delete them.
Questions, or did this not match your box?
Every guide here came from a real problem someone hit. If yours behaves differently, say so — that is how these get corrected, and how the fix gets prioritised.
We answer there rather than in a comment box, because that is where the people who have already solved it are.