Skip to content

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 watch the logs including the last 100 messages (omit --tail=100 to see them all, and -f to output only the last logs without watching them):

docker compose logs -f --tail=100

Before reporting a bug:

MariaDB

Should MariaDB get stuck in a restart loop and PhotoPrism cannot 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_LOG_LEVEL to "debug" in the environment: section of the photoprism service (or use the --debug flag when running the photoprism command directly):

services:
  photoprism:
    environment:
      PHOTOPRISM_LOG_LEVEL: "debug"

If you need even more detailed logs for debugging, you can enable trace log mode by setting PHOTOPRISM_LOG_LEVEL to “trace” in the environment: section of the photoprism service (or use the --trace flag when running the photoprism command directly):

services:
  photoprism:
    environment:
      PHOTOPRISM_LOG_LEVEL: "trace"

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 compose.yaml. 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

Make sure you have Docker or Docker Desktop installed, started, and properly configured on your system. It is available for Mac, Linux, and Windows. On Red Hat-compatible Linux distributions like RHEL, CentOS, Fedora, AlmaLinux, and Rocky Linux, you can use Podman and Podman Compose as direct replacements for Docker and Docker Compose.

↪ 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", "failed to create folder", "permission denied", 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 cannot 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
  • Your password contains one or more $ signs that were not properly escaped in your compose.yaml or docker-compose.yml file (escape them and reset your database or manually set a new password)
  • The password may be correct, but the username is wrong and does not match PHOTOPRISM_ADMIN_USER
  • There is a problem with the schema or data in the auth_sessions database table that can be resolved by running the photoprism auth reset --yes command in a terminal to reset it to a clean state and force a re-login of all users (this will also delete all client access tokens and app passwords users may have created)
  • You upgraded from an early test or preview build and might need to run the photoprism users reset --yes command in a terminal after the upgrade, see Known Issues for details (this resets the auth_users table to a clean state and requires accounts to be recreated)
  • 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

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, 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", "failed to create folder", "permission denied", 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)

To see which user accounts exist on your instance, 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.

No WebDAV Access

If you followed our step-by-step guide and still have trouble connecting via WebDAV:

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 do not 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 have tried to download multiple pictures or albums and found that some files are missing in the resulting zip archive or you got the error message "No files available for download":

Also make sure that there is enough free disk space available, since the server creates a temporary zip file when multiple pictures are selected for download. Complete albums are compressed while downloading without needing temporary storage.

File Downloads

Follow the steps to resolve zip download issues if you are having problems downloading selected pictures, individual files, or stacks of files that belong to a single photo.

If this didn't help, the problems might be caused by your browser settings, e.g. insufficient permissions to download multiple files, browser plugins, a firewall, VPN, CDN or proxy that you use together with PhotoPrism.

Wrong Search Results

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

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 do not contain anything helpful:

  • The issue can be resolved by reloading the page or clearing the browser cache
  • You browse non-JPEG files under Library > Originals which have an icon but no preview
  • Preview Images are disabled under Settings > Content (enable them)
  • Dynamic Previews are disabled under Settings > Advanced or your server is not powerful enough
  • The sizes in Settings > Advanced have been changed so the request can't be fulfilled
  • FFmpeg and/or RAW converters are disabled under Settings > Advanced (enable them)
  • Your storage folder is full, or a quota/inode limit has been reached (increase it)
  • Your storage folder is not writable or mounted read-only (change permissions)
  • Your cache storage folder is not accessible, has been renamed, or was not mounted on a permanent volume, so the cached thumbnails have been lost after a restart (run the photoprism thumbs command in a terminal to regenerate them after fixing this)
  • Originals or thumbnail files were deleted manually, for example to free up disk space
  • Files cannot be opened, e.g. because the file system permissions have been changed
  • Files are stored on an unreliable device such as a USB flash drive or a shared network folder
  • Some thumbnails could not be created because you didn't configure at least 4 GB of swap
  • 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)
  • Your proxy, router, or firewall has a request rate limit, so some requests fail
  • There are other network problems caused by a firewall, router, or unstable connection
  • An ad blocker or other plugins block requests (disable them or add an exception)
  • You are connected to the wrong server, VPN, CDN, or a DNS record has not been updated yet

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", "failed to create folder", "permission denied", 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:

  • You are using an incompatible browser, e.g. without AVC support (try another browser)
  • AVC support or related JavaScript features have been disabled in your browser (check the settings and try another browser)
  • It is a large non-AVC video that needs to be transcoded first (wait or run photoprism convert to pre-transcode videos)
  • An ad blocker or other plugins block requests (disable them or add an exception)
  • Your (virtual) server disk is full, or a quota/inode limit has been reached (increase it)
  • The storage folder is not writable or mounted read-only (change permissions)
  • Files are stored on an unreliable device such as a USB flash drive or a shared network folder (check if the files are accessible)
  • 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)
  • There are other network problems caused by a proxy, firewall, or unstable connection (try a direct connection)
  • You are connected to the wrong server, VPN, CDN, or a DNS record has not been updated yet

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:

  1. 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.
  2. 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.
  3. 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.