Troubleshooting Checklists¶

You are welcome to ask for help in our community chat. Sponsors receive direct technical support via email. Before submitting a support request, try to determine the cause of your problem.

Connection Fails¶

If your browser cannot connect to the Web UI even after waiting a few minutes, run this command to display the last 100 log messages (omit --tail=100 to see all):

docker compose logs --tail=100

Before reporting a bug:

MariaDB¶

Should MariaDB get stuck in a restart loop and PhotoPrism can't connect to it, this indicates a memory, filesystem, or other permission issue:

mariadb: mysqld: ready for connections.
mariadb: mysqld (initiated by: unknown): Normal shutdown
photoprism: dial tcp 172.18.0.2:3306: connect: no route to host
mariadb: mysqld: Shutdown complete

Learn more ›

Firewall¶

Maps & Places: As explained in our Privacy Policy, reverse geocoding and interactive world maps depend on retrieving the necessary information from us and MapTiler AG, headquartered in Switzerland. You therefore need allow requests to these API endpoints if you have a firewall installed and make sure your Internet connection is working.

Learn more ›

IPTables: On Linux, Docker manipulates the iptables rules to provide network isolation. This does have some implications for what you need to do if you want to have your own policies in addition to the rules Docker manages.

Learn more ›

Debug Mode¶

To enable debug mode, set PHOTOPRISM_DEBUG to "true" in the environment: section of the photoprism service (or use the --debug flag when running the photoprism command directly):

services:
  photoprism:
    environment:
      PHOTOPRISM_DEBUG: "true"

Then restart all services for the changes to take effect. It can be helpful to keep Docker running in the foreground while debugging so that log messages are displayed directly. To do this, omit the -d parameter when restarting:

docker compose stop
docker compose up

If you see no errors or no logs at all, you may have started the server on a different host and/or port. There could also be an issue with your browser, browser plugins, firewall settings, or other tools you may have installed.

The default Docker Compose config filename is docker-compose.yml. For simplicity, it doesn't need to be specified when running docker compose or docker-compose in the same directory. Config files for other apps or instances should be placed in separate folders.

Docker Doesn't Work¶

Users of Red Hat-compatible Linux distributions such as Red Hat Enterprise Linux®, CentOS, Fedora, AlmaLinux, and Rocky Linux can substitute the docker and docker compose commands with podman and podman-compose as drop-in replacements.

↪ Getting Docker Up and Running

Bad Performance¶

↪ Performance Tips

↪ Solving Windows-Specific Issues

Fatal Server Errors¶

Fatal errors are often caused by one of the following conditions:

We recommend checking your Docker Logs for messages like disk full, disk quota exceeded, no space left on device, read-only file system, error creating path, wrong permissions, no route to host, connection failed, and killed:

If a service has been "killed" or otherwise automatically terminated, this points to a memory problem (add swap and/or memory; remove or increase usage limits)
In case the logs show "disk full", "quota exceeded", or "no space left" errors, either the disk containing the storage folder is full (add storage) or a disk usage limit is configured (remove or increase it)
Errors such as "read-only file system", "error creating path", or "wrong permissions" indicate a filesystem permission problem
Log messages that contain "no route to host" indicate a problem with the database or network configuration (follow our examples)

Start a full rescan if necessary, for example, if it looks like thumbnails or pictures are missing.

App Not Loading¶

If the app doesn't load in your browser when you navigate to the server URL, you can check the browser console for helpful errors and warnings. Sometimes you just need to wait a moment, for example, if you are using a slow wireless connection or the server was started only a few seconds ago. In case this does not help:

You are using an incompatible browser (try another browser)
JavaScript is disabled in your browser settings, so you only see the splash screen (enable it)
JavaScript was disabled by a browser plugin (disable it or add an exception)
Your browser cannot communicate properly with the server, e.g. because a reverse proxy, VPN, or CDN is configured incorrectly (check its configuration and try without)
HTTP security headers prevent the app from loading in a frame (override them)
An ad blocker or other plugins block requests (disable them or add an exception)
There is a problem with your network connection (test if other sites work)
You are connected to the wrong server, VPN, CDN, or a DNS record has not been updated yet

Cannot Log In¶

If password authentication is enabled and the user interface loads, but you can't log in with what you assume is the correct password:

There is a problem with the integrity, stability or connection of the database that you should be able to diagnose by watching the logs for errors and warnings
You had too many failed login attempts, therefore another attempt from your computer is temporarily not possible
Caps Lock is enabled on your keyboard, your computer has the wrong input locale set, or somebody else might have changed the password without telling you
PHOTOPRISM_ADMIN_PASSWORD does not have a minimum length of 8 characters, so PhotoPrism has been started without a password since there is no default
The password may be correct, but the username is wrong and does not match PHOTOPRISM_ADMIN_USER
You upgraded from a Development Preview and might need to run the photoprism users reset --yes command in a terminal after the upgrade, see Known Issues for details
Your browser cannot communicate properly with the server, e.g. because a reverse proxy, VPN, or CDN is configured incorrectly (check its configuration and try without)
You are connected to the wrong server, VPN, CDN, or a DNS record has not been updated yet
Remember that the initial admin username and password cannot be changed after PhotoPrism has been started for the first time

To see which user accounts exist, open a terminal and run photoprism users ls. A new password can be set with photoprism passwd [username]. You can then try to log in again. Upgrade to the latest release, restart the server, and check the logs for errors and warnings if it still doesn't work.

Missing Pictures¶

If you have indexed your library and some images or videos are missing, first check Library > Errors for errors and warnings. In case the application logs don't contain anything helpful:

Depending on the cause of the problem, you may need to perform a full rescan once the issue is resolved.

Zip Archives¶

When you want to download multiple pictures and find that some of them are missing from the resulting zip archive, or you get the error message "No files available for download":

Index your library and wait until indexing is complete, as your index may be incomplete or out of date
In some cases, you may have to perform a complete rescan of your library, for example after upgrading to a new major release

Wrong Search Results¶

If search results are incorrect, for example, in the wrong order or not filtered properly:

Indexing is still in progress and has not been completed yet
You need to re-index your pictures, for example after updating PhotoPrism
Previously failed migrations must be re-run to update the index schema
The database server is incompatible or needs to be updated

It may be a bug if you cannot find any other reasons, such as a local configuration problem or a misunderstanding in how the software works. Please note that reports must be reproducible in order for us to provide a solution.

Broken Thumbnails¶

If some pictures have broken or missing thumbnails, first check Library > Errors for errors and warnings. In case the application logs don't contain anything helpful:

We also recommend checking your Docker Logs for messages like disk full, disk quota exceeded, no space left on device, read-only file system, error creating path, wrong permissions, and killed:

If a service has been "killed" or otherwise automatically terminated, this points to a memory problem
In case the logs show "disk full", "quota exceeded", or "no space left" errors, either the disk containing the storage folder is full (add storage) or a disk usage limit is configured (remove or increase it)
Errors such as "read-only file system", "error creating path", or "wrong permissions" indicate a filesystem permission problem

Depending on the cause of the problem, you may need to perform a full rescan once the issue is resolved.

Videos Don't Play¶

In case FFmpeg is disabled or not installed, videos cannot be indexed because still images cannot be created. You should also have Exiftool enabled to extract metadata such as duration, resolution, and codec.

If videos do not play and/or you only see a white/black area when you open a video:

We recommend that you check your Docker Logs and the browser console for messages related to HTTP requests, permissions, security, FFmpeg, videos, and file conversion.

Please note:

Not all video and audio formats can be played with every browser. For example, AAC - the default audio codec for MPEG-4 AVC / H.264 - is supported natively in Chrome, Safari, and Edge, while it is only optionally supported by the OS in Firefox and Opera.
HEVC/H.265 video files can have a .mp4 file extension too, which is often associated with AVC only. This is because MP4 is a container format, meaning that the actual video content may be compressed with H.264, H.265, or something else. The file extension doesn't really tell you anything other than that it's probably a video file.
MPEG-4 AVC videos are not re-encoded if they exceed the configured bitrate limit. To reduce the size of AVC videos, you can manually replace the original files with a smaller version or wait for a future release that offers this functionality.

We kindly ask you not to report bugs via GitHub Issues unless you are certain to have found a fully reproducible and previously unreported issue that must be fixed directly in the app. Ask for technical support if you need help, it could be a local configuration problem, or a misunderstanding in how the software works.