Runtipi wouldn’t start: a filesystem permission trap

I installed Runtipi on my NAS about three weeks ago. Smooth setup, the one-click app store worked exactly as advertised, and within an hour I had Ollama and Open WebUI running side by side. Then I powered down for some maintenance, brought everything back up, and Runtipi refused to start. The container would spin up for maybe two seconds, then exit with code 1.

The error message that wasn’t helpful

First thing I did was check the logs.

docker logs runtipi-app-1

Nothing. Actually worse than nothing — it just said the container exited. So I checked docker-compose logs from the Runtipi directory itself:

cd /opt/runtipi && docker compose logs

Still nothing useful. Just a graceful exit with no error trace. I spent probably forty minutes assuming this was a permissions issue because that’s the default culprit in self-hosted stuff. I checked the ownership of the Runtipi directory, checked if my user was in the docker group, verified the socket permissions. Everything looked correct.

The frustrating part is that Runtipi doesn’t really have debug logging turned on by default, so you get this void where actual information should be. I appreciate that the project tries to keep things simple, but when something breaks, simple doesn’t help you fix it.

What I tried that changed nothing

I rebuilt the container from scratch thinking maybe an update broke something:

docker compose down
docker compose pull
docker compose up -d

Nope. Still exited immediately.

I checked if the app store microservice was the problem by temporarily removing it from the compose file and just running the core Runtipi container. Still failed. I even checked disk space — the NAS had 200GB free, so that wasn’t it.

At one point I started wondering if the issue was with the host’s Docker daemon itself. I restarted Docker. Restarted the whole NAS. Cleared out the compose cache. You know the drill when you’re just throwing things at the wall.

The actual problem: a stale data volume

What finally cracked it open was running docker in verbose mode to see what the container was actually doing at startup:

docker compose up --verbose

That’s when I saw it buried in the noise: a mounting error for the data volume. Not a permissions error — a filesystem corruption error on the NAS’s ext4 volume where Runtipi stores its persistent data.

The volume was still mounted, but when Docker tried to write the initial config files, the filesystem returned read-only errors. My NAS had apparently detected some corruption during the shutdown and remounted that partition as read-only as a safety measure. Classic behavior, but Runtipi’s startup just silently failed instead of surfacing that.

I had to go into the NAS’s terminal and run an fsck on that specific volume:

sudo fsck.ext4 -y /dev/sda3

This took about eight minutes and found a handful of orphaned inodes. After the repair, I brought the volume back online, and then Runtipi started without complaint.

Why this matters

Runtipi is genuinely useful for the use case it targets. Spinning up Ollama or Stable Diffusion with one click instead of wrestling with docker-compose files is real convenience. But the trade-off is abstraction — when something goes wrong, you’re sometimes left debugging in the dark because the orchestration layer hides the actual Docker internals.

The fix wasn’t Runtipi’s fault, but Runtipi’s error handling made the diagnosis harder than it needed to be. A more verbose startup log, or a health check that actually reports what it’s checking, would have saved me the forty-minute detour into a false permissions rabbit hole.

So the lesson here isn’t that Runtipi is broken. It’s that when you abstract away Docker, you need either bulletproof error messages or a way to drill down into what’s actually happening. Runtipi has neither yet, and that’s worth knowing before you rely on it for anything critical.

Explore Runtipi in our AI Homelab Toolkit.