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:

• Check the 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 Docker network configuration (follow our examples)
• Make sure you are using the correct protocol (default is http), port (default is 2342), and hostname or IP address (default is localhost)
• Note that HTTP security headers will prevent the app from loading in a frame (override them)
• Verify your computer meets the system requirements
• Go through the checklist for fatal server errors

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

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 the docker-compose command in the same directory. Config files for other apps or instances should be placed in separate folders.

Docker Doesn't Work

↪ Getting Docker Up and Running

MariaDB Issues

↪ Troubleshooting MariaDB Problems

MySQL Errors

↪ Official support for MySQL 8 is discontinued

Bad Performance

↪ Performance Tips

Fatal Server Errors

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

• Your (virtual) server disk is full (add storage)
• You have accidentally mounted the wrong folders (update config and restart)
• There is disk space left, but a usage or the inode limit has been reached (change it)
• The storage folder is not writable or mounted read-only (change permissions)
• Symbolic links were mounted or used within a storage folder (replace with actual paths)
• The server is low on memory (add memory)
• You didn't configure at least 4 GB of swap space (add swap)
• High-resolution panoramic images require additional memory above the recommended minimum (add more swap or memory)
• The server CPU is overheating (improve cooling)
• The server has an outdated operating system that is not fully compatible (update)
• The server hardware is defective and causes random panics (test on another server)
• The database server is not running, incompatible, or misconfigured (start, upgrade, or fix it)
• You've upgraded the MariaDB server without running mariadb-upgrade
• Files are stored on an unreliable device such as a USB flash drive or a shared network folder
• There are network problems caused by a bad configuration, firewall, or unstable connection
• Kernel security modules such as AppArmor and SELinux are blocking permissions
• Your Raspberry Pi has not been configured according to our recommendations

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

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:

• The pictures are in Review due to low quality or incomplete metadata
• The file type is generally unsupported
• The file type is generally supported, but a specific feature or codec is not
• The originals have bad filesystem permissions, so they cannot be opened by the indexer
• The indexer has skipped the files because they are exact duplicates
• The files are ignored based on pattern in a .ppignore file
• They are in Library > Hidden because thumbnails could not be created:
  • Convert to JPEG is disabled in Settings > Library (enable it)
  • FFmpeg and/or RAW converters are disabled in Settings > Advanced
  • The file is broken, e.g. because of short Huffman data (try to fix it)
  • Your (virtual) server disk is full (add storage)
  • The storage folder is not writable (change permissions)
  • A disk usage or the inode limit has been reached (remove or increase it)
• Multiple files were stacked based on their metadata or file names
• The private or archived status was restored from a backup
• The NSFW filter is enabled, so they were marked as private
• You are not signed in as admin, so you can't see everything
• You try to index a shared drive on a remote server, but the server is offline
• The indexer has crashed because you didn't configure at least 4 GB of swap
• Somebody has deleted files without telling you
• You are connected to the wrong server, VPN, CDN, or a DNS record has not been updated yet

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

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:

• The issue can be resolved by reloading the page or clearing the browser cache
• You browse non-JPEG files in Library > Originals which have an icon but no preview
• Dynamic Previews are enabled in Settings > Advanced, but the 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 in Settings > Advanced (enable them)
• Convert to JPEG is disabled in Settings > Library (enable it)
• Your (virtual) server disk is full (add storage)
• A disk usage or the inode limit has been reached (remove or increase it)
• The storage folder is not writable or mounted read-only (change permissions)
• Files were deleted manually, for example to free up disk space
• Files can't 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", 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

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 (add storage)
• A disk usage or the inode limit has been reached (remove or 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.

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.