Troubleshooting

First, where to look#

Two places answer most questions before you need this page.

The Tasks page. Everything LibrePortal does, from installing an app to taking a backup, runs as a task, and the task keeps its full output. Open Tasks in the top bar, find the one marked Failed, and press Logs. The last few lines usually say what went wrong in plain words.

The health check. On the server:

sudo -u libreportal libreportal system status

Docker:       reachable
WebUI:        running, port 4821, reachable
Crash loops:  0
Checked:      2026-09-30T09:12:44+01:00

That tells you whether Docker is running, whether the WebUI is up and on which port, and whether any app keeps crashing and restarting. For the deeper checks the installer ran, with the reasons behind each one, use libreportal system check --details.

The logs live in /libreportal-system/logs/. libreportal.log is the main one; error_report.log lists every step that has ever failed, with where it failed.

"Script is NOT able to run from this user"#

What you see: you typed libreportal something and got "This script should ONLY be run as: libreportal".

Why: the libreportal command only runs as the libreportal user, never as you or as root. That's deliberate: it keeps what LibrePortal can do on the machine to the few jobs it's been given.

The fix: put sudo -u libreportal in front:

sudo -u libreportal libreportal help

Every command in this guide is written that way.

I've lost the WebUI login#

What you see: you can reach the sign-in page but don't have the username or password. Perhaps the install card said run: libreportal webui login show and you never did.

The fix: print it:

sudo -u libreportal libreportal webui login show

That shows the username, the password and every address the WebUI can be opened at. The password the installer printed near the start, as Generated password for the 'libreportal' system user, is not this one; that belongs to the libreportal account on the machine.

If you'd rather have a new login altogether:

sudo -u libreportal libreportal webui login reset

That makes a new random username and password, restarts the WebUI and prints them. Anyone signed in with the old ones is signed out.

How to check: sign in with what it printed. Then put it in your password manager.

The WebUI won't load#

What you see: the browser says it can't connect, or times out.

Likely causes, most common first:

• The wrong port. The WebUI's port is picked at random when LibrePortal is installed, and a reinstall picks a new one. An old bookmark points nowhere. webui login show prints the right address.
• You're not somewhere it answers. If the WebUI is set to answer only your trusted places (the setup wizard recommends it), then from a phone on mobile data, or from work, it won't load at all. Use the LibrePortal VPN, or see Who can reach what.
• The WebUI isn't running. system status says so on its WebUI: line. sudo -u libreportal libreportal app restart libreportal starts it again.

To check: confirm app restart libreportal brings the WebUI back when its container is down

How to check: system status shows WebUI: running, port …, reachable, and that address opens in a browser on the same network.

The browser refuses the WebUI after I changed HTTPS#

What you see: after changing the HTTPS setting, the browser shows a certificate error you can't get past, or a blank page.

Why: the WebUI's own page is now served over HTTPS with a certificate your browser doesn't trust, or one that doesn't match the address you're using.

The fix: put the WebUI back on plain http://:

sudo -u libreportal libreportal webui repair

It switches the WebUI's page security back to HTTP, removes its certificate, restarts it and prints "The admin page is on plain HTTP again. Open it at:" with the addresses. Domains and HTTPS explains how to set HTTPS up so it sticks.

I locked myself out after changing who can reach the WebUI#

What you see: you changed Admin page on Admin → Tools → Access (or SSH), and now the page won't load.

The fix: wait ten minutes. Any change that could lock you out undoes itself after 10 minutes, unless you confirmed it from the new way in. That's why the Access page shows Waiting for your confirmation with a countdown after you apply something: if you can still see the page, press Confirm. If you can't, the change reverts on its own, even if the server reboots in the meantime.

If you can't wait, or you did confirm and still regret it, turn the protection off from the server:

sudo -u libreportal libreportal security lockdown off

If you can't even get in over SSH, use the machine's own console (at its keyboard, or your provider's web console for a VPS) and run, as root:

sudo /usr/local/lib/libreportal/libreportal-adminaccess off

Both open the WebUI's port again. Who can reach what has the details of the Access page.

An app won't start after I unplugged a disk#

What you see: an app that lives on a USB or second disk won't start, or its task fails.

Why: on purpose. When a disk isn't plugged in, its folder is still there, just empty. An app started there would begin again from nothing and fill up your system disk, so LibrePortal refuses to start it.

The fix: plug the disk back in and make sure it's mounted, then start the app again. storage list shows each location's state; a missing one says "drive not mounted — apps here will not start".

sudo -u libreportal libreportal storage list
sudo -u libreportal libreportal app start jellyfin

To stop it happening after a reboot, make the disk mount itself with storage fstab-add. Disks and storage has more.

An app won't install because a port is in use#

What you see: the install stops with "Port 53/udp is used by … on this server, and adguard needs it", or the install dialog's Requirements step shows a port marked ✗.

Why: something else on the machine is already using a port the app needs. For most apps LibrePortal picks a free port at random, so this happens with apps that need a particular number: a DNS server needs 53, a mail server needs 25, Traefik needs 80 and 443.

The fix: the message names what's using it, and suggests how to free it. Either stop that other program, or, if the app allows it, give the app a different port on the Network tab of its Config page before installing. For ports that have to be a particular number, freeing the port is the only way.

How to check: open the install dialog again; the port row shows ✓ Ports free.

An update was rolled back#

What you see: the app's Updates tab says the last update failed, and its history shows a rollback. With notifications on, you got a message like "Update of nextcloud failed".

Why: the new version didn't start, or started but didn't pass its health check, so LibrePortal put the snapshot it took beforehand back. Your app is running the version it had before, with its data as it was just before the update.

Sometimes the failure comes earlier: LibrePortal couldn't take the snapshot, so it stopped before touching the app at all. The message then says the app is still on the version it had, and asks you to check its backups. That usually means no backup location is enabled, or the one that is can't be reached; see A backup failed below.

What to do: nothing urgent. The app works. A version that failed an automatic update is never tried automatically again, so it won't keep happening. Look at the failed task's log for the reason; often it's a problem in that release, fixed in the next one. When a newer version appears, press Update to try it.

If an update went through but the app is wrong afterwards, you can roll it back yourself.

A backup failed#

What you see: a red mark on Admin → Backups, or a message "Backup of … failed".

Why: usually the backup location: a USB disk that isn't plugged in, a full disk, or a remote server that couldn't be reached. Your earlier snapshots are untouched.

The fix: open the failed task on the Tasks page and read the end of its log. Fix what it points at, then press Backup now on the app's Backups tab. To check a location and see how full it is:

sudo -u libreportal libreportal backup location list
sudo -u libreportal libreportal backup location stats

A snapshot marked Last backup could not be read back was written but failed its check. Take it seriously; check the location's disk, then back up again. Backups and restore has more.

If your backups go to a Backup Server and it's the one that's out of reach, see When something's wrong.

"libreportal update" did nothing over SSH#

What you see: you ran libreportal update over SSH or from a script, and it said "Nothing answered the update prompt".

Why: with the Auto Apply Updates setting off, plain libreportal update stops and asks a yes/no question, and there was nobody to answer it.

The fix: use the version that never asks:

sudo -u libreportal libreportal update apply

The installer said "complete" but nothing works#

What you see: the install finished with its card, but the WebUI address doesn't load.

Why: the installer keeps going when a step fails, so it can tell you everything at the end rather than stopping at the first problem. That means "complete" doesn't always mean every step worked.

The fix: read the end of the install log, /libreportal-system/logs/install-<date>-<time>.log, and look at /libreportal-system/logs/error_report.log, which lists every step that failed. Then run system check --details. Fix what they point at and run the install command again; on a machine that already has LibrePortal, it upgrades in place and fills in whatever was missed.

Still stuck?#

Look at Questions people ask and the page for the part that's misbehaving. If you think you've found a bug, Support us → Tell us what broke in the WebUI's top bar explains how to report it. Include the failed task's log; it's the most useful thing you can send.