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:
- 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", "failed to create folder", "permission denied", or "wrong permissions" indicate a filesystem permission problem
- It may help to add the
:z
mount flag to volumes when using SELinux (Red Hat/Fedora) - 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 is2342
), and host (default islocalhost
):- Check if the server port you try to use has been exposed and no firewall is blocking it
- Only use
localhost
or127.0.0.1
if the server is running on the same computer (host) - Avoid using IP addresses other than
127.0.0.1
directly, as they can change - We recommend configuring a local hostname to access other hosts on your network
- If you use a firewall, ensure that it is configured correctly and that outgoing connections to our geocoding API are allowed
- 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
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
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.
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.
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 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¶
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¶
↪ Solving Windows-Specific Issues
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)
- You are using a filesystem or network drive with a file size limit (change settings or storage)
- 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)
- RAW images and/or high-resolution panoramas 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", "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 yourcompose.yaml
ordocker-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 thephotoprism 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 theauth_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:
- WebDAV has been disabled for all users in the advanced settings
- WebDAV is unavailable because your instance is running in public mode (disable it)
- You are trying to connect to an invalid path, try
/originals/
without omitting the/
at the end, and read our notes on installing PhotoPrism in a subdirectory on a shared domain - Your user account role is not permitted to use WebDAV (try as User or Admin)
- WebDAV access has not been enabled for your user account (enable it)
- You are experiencing a general authentication problem, see Cannot Log In
- Your WebDAV client requires a secure connection (connect via HTTPS)
- Your instance or reverse proxy uses an invalid HTTPS/TLS certificate
- As a Windows user, you may need to change the basic authentication level
- 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, 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 do not contain anything helpful:
- The files exceed the size limit in megabyte or the resolution limit in megapixels
- The files have bad filesystem permissions or the wrong owner, so they cannot be opened
- 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 indexer has skipped the files because they are exact duplicates
- The indexer has skipped the files because they have an incorrect extension that does not match their actual format, e.g. JPEG images with a
.heic
extension - The files are ignored based on pattern in a
.ppignore
file - They are in Library > Hidden because thumbnails could not be created:
- Preview Images are disabled under Settings > Library (enable them)
- FFmpeg and/or RAW converters are disabled under Settings > Advanced
- The file is broken, e.g. because of short Huffman data (try to fix it)
- 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)
- 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 cannot see everything
- You try to index a shared drive on a remote server, but the server is offline
- Somebody has deleted files without telling you
- Your server does not have at least 4 GB of swap or a hard memory limit is configured, which may cause unexpected restarts when the indexer temporarily needs more memory to process large files
- Indexing RAW images and high-resolution panoramas may require additional swap space and/or physical memory beyond the recommended minimum
- 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.
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":
- Your index may be out of sync with the file system (reindex your library and wait until the operation has been completed)
- In order to include RAW, XMP and/or generated sidecar files, your download preferences may need to be changed under Settings > General
- If this didn't help, you may need to perform a complete rescan of your library, e.g. after upgrading to a new release or restoring your index from a backup
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:
- 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 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 > Library (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:
- 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.