Skip to content

Troubleshooting

Troubleshoot your server: logs, diagnostics report and detailed logging Watch on YouTube

Most problems have a quick fix, and this page walks you through the common ones. The logs almost always point the way.

Inside Frameleaf, select Help at the top of any page to search every guide or ask a question. Administrators can see what failed and why in Settings, then Computers & background work, then Background work, under Advanced.

If you installed with Manager, start with Services: choose Logs beside a service, or Check connections under Troubleshooting, and read the error recorded for the operation in Activity. Keep Manager’s own folder and the database folders in place while you work out what went wrong.

Still stuck? Read the release notes for known issues, then search or ask in GitHub Issues and GitHub Discussions. Include your Frameleaf version, how you installed it and the relevant lines from the logs, so people can help you faster.

Terminal window
docker ps # running containers
docker ps -a # running and stopped containers

From the folder with your docker-compose.yml, you can also use:

Terminal window
docker compose ps

You can also read the logs in the browser, without a terminal: open Settings, then Server & updates, then Advanced, then Server logs. Search them, filter by part of the server and by Problems only, follow new lines live, and Download… the last few days as a .zip file to send to whoever is helping you. See Read the logs.

Terminal window
docker logs frameleaf_server
docker logs frameleaf_machine_learning
docker logs frameleaf_postgres

Add --follow to keep streaming new lines while you reproduce a problem. If your containers have different names, use the ones docker ps shows:

Terminal window
docker logs frameleaf_server
docker logs --follow frameleaf_machine_learning

To make the server log more, set FRAMELEAF_LOG_LEVEL in .env. See Environment variables and Monitoring.

Terminal window
docker exec -it frameleaf_server bash
docker exec -it frameleaf_machine_learning bash
Terminal window
docker exec -it frameleaf_server frameleaf-admin version
docker exec -it frameleaf_server frameleaf-admin list-users
docker exec -it frameleaf_server frameleaf-admin reset-admin-password

See Server commands.

docker compose fails with “unknown shorthand flag: ‘d’” or “permission denied”

Section titled “docker compose fails with “unknown shorthand flag: ‘d’” or “permission denied””

Run docker compose version to check you have Compose v2. An unknown shorthand flag error usually means an old or incompatible Docker package. An .env: permission denied error means the user running Compose can’t read that file, so check its permissions. To get a current version, follow Docker’s Engine install guide for your distribution, including Uninstall old versions and Install using the apt repository (or rpm), to replace it with Docker’s own packages.

“‘name’ does not match any of the regexes: ‘^x-’”

Section titled ““‘name’ does not match any of the regexes: ‘^x-’””

You ran docker-compose (with a hyphen), which is deprecated and isn’t supported. Use docker compose from a current Docker install.

“can’t set healthcheck.start_interval”

Section titled ““can’t set healthcheck.start_interval””

The full message is can't set healthcheck.start_interval as feature require Docker Engine v25 or later. Update to Docker Engine v25 or later, and keep the health checks in place: they tell you when a container fails to start. See Unraid.

  1. Check the required containers are running with docker compose ps. If one keeps restarting, read its logs.
  2. Open http://<server-ip>:2283, using the server’s address on your network, not localhost, from another device.
  3. On Synology, check the firewall and HTTPS settings. The native app uses the configured DSM HTTPS origin and port, normally 5001, through /frameleaf-manager/. Its Manager listener on 9443 stays local to the NAS. Your photo library uses its separate application port, normally 2283. Inspect server and database logs in Frameleaf Manager, then Services, then Logs beside the service.
  4. If you use a reverse proxy, try the direct address first to rule it out. See Reverse proxy.
  • A new server can only be set up from its home network. Open the web app, or use the Frameleaf app, from a device on the same network, not through remote access or a proxy on the internet. For a server that isn’t at home, see Setting up a new server remotely.
  • Setup ends once the server has an administrator. If someone has already set it up, sign in with that account.
  • If the server is already linked to a Frameleaf account, the apps join it with Sign in with Frameleaf instead of setting it up.

Check this server is the last step before Manager installs, imports or restores. Nothing is downloaded or changed while it looks. It shows every problem at once, with the steps for your server: Unraid, TrueNAS, HexOS or plain Docker. Only a problem stops the install. Warnings and Couldn’t check results are worth knowing, but Frameleaf can still install. After you fix something, select Check again.

If you’re stuck, select Download a report at the bottom of the check to share when you ask for help. Manager removes passwords, folders and file names, but read it before you post it.

  • Manager can’t use Docker. Docker didn’t answer. On Unraid, open Settings → Docker and check Enable Docker is set to Yes. On TrueNAS, open Apps and check a pool is chosen and Apps are running. On HexOS, check Applications are running, or restart the server. On plain Docker, start it, for example with sudo systemctl start docker. Then open Manager again and check again.

  • This version of Docker is too old. Frameleaf needs Docker 24 or newer, on a 64-bit Intel, AMD or ARM processor. On Unraid, open Tools → Update OS. On TrueNAS, open System → Update. On HexOS, update HexOS. On plain Docker, install the current Docker Engine from docs.docker.com/engine/install.

  • Docker Compose is too old. Frameleaf needs Docker Compose 2 or newer. Update your NAS as above, or on plain Docker install the current Docker Engine and its Compose plugin.

  • Docker is part of a swarm. Frameleaf runs on a single Docker server, not a swarm. Run docker swarm leave --force on this server. Apps the swarm runs stop.

Not enough room in Docker’s storage means Docker can’t fit Frameleaf’s images. Frameleaf needs about 4 GB there without machine learning, and about 8 GB with machine learning on the CPU. The message says how much it needs and how much is free.

  • Unraid: Docker lives in a fixed-size docker.img. Open Settings → Docker and set Enable Docker to No; your containers stop while Docker is off. Raise Docker vDisk size to at least 40 GB, turn Docker back on, then open Manager again.
  • TrueNAS: open Apps → Configuration → Choose Pool to see which pool holds your apps. Free some space on that pool, or remove apps you no longer use.
  • HexOS: free some space on the drive that holds your applications, or remove apps you no longer use.
  • Plain Docker: free some space on the drive that holds /var/lib/docker. To clear images no container uses, run docker image prune -a.

Couldn’t check Docker’s storage means Manager couldn’t see how much room Docker has. Frameleaf can still install. If it runs out, the install stops at that point and tells you.

These apply to Photos and videos, Database, Thumbnails and Backups. When you chose the folder in Manager, Choose another folder fixes most of them in one step.

  • Manager can’t reach the … folder. The folder isn’t on a drive Manager can use, or isn’t connected to Manager yet. On Unraid, open the Docker tab, click Frameleaf Manager, choose Edit, then Add another Path, Port, Variable, Label or Device, set this folder as both the Container Path and the Host Path, and Apply. On TrueNAS, open Apps, choose Frameleaf Manager, select Edit, add the folder under volumes with the same path on both sides and add it to the variable the check names, then save. On HexOS, check the Applications location you chose for Frameleaf is on a drive inside this server. On plain Docker, stop Manager and run the launcher again with this folder, or add its drive.

  • Manager can’t save in the … folder. The folder is read-only to Manager. On Unraid, edit Frameleaf Manager in the Docker tab and set this folder’s Access Mode to Read/Write. On TrueNAS, open Datasets, choose the dataset that holds the folder, select Edit under Permissions, and give the apps user read and write access. On HexOS, give Frameleaf read and write access in the folder’s settings. On plain Docker, check the folder isn’t on a read-only drive, or a network share that maps root to another user.

  • Not enough room in the … folder. The drive that holds it is nearly full. Free some space on that drive, or choose a folder on a bigger drive.

  • These folders overlap. Photos and videos, the database, backups and Manager’s own settings each need their own separate folder. Choose separate folders.

  • Thumbnails can’t go in this folder. It’s a network share. Thumbnails need a drive inside this server. Choose another folder.

  • The thumbnails drive isn’t connected. The thumbnails folder isn’t there, so its drive may be disconnected or not mounted. Nothing has been changed. Reconnect the drive, or choose another folder. When restoring a backup, you can also keep thumbnails with your photos: see Restore when the thumbnail drive is gone.

  • The photos drive isn’t connected. A photos folder isn’t there. Its drive may be disconnected or not mounted. Nothing has been changed. Reconnect it.

  • A folder Frameleaf uses isn’t there. Its drive may be disconnected or not mounted. Nothing has been changed. Reconnect it.

  • A media volume is missing. A Docker volume your library uses isn’t on this server. Create or restore that Docker volume.

To reconnect a drive: on Unraid, open Main and check the drive or pool that holds the folder is mounted; for an Unassigned Devices drive, click Mount. On TrueNAS, open Storage and check the pool is online. On HexOS, check the drive is connected and healthy. On plain Docker, connect the drive and mount it at the same place, for example with sudo mount -a.

The database is on hard drives is a warning, not a problem. Frameleaf will work, but Manager found a faster drive with room. Select Use with the drive’s name to put the database there, or carry on. See Fast drives for the database and thumbnails.

  • Not enough room in Manager’s own folder. Manager saves each database backup there before it moves to your backups folder. Free some space on that drive. On Unraid, that’s usually the cache pool that holds appdata. On TrueNAS, it’s the pool that holds Frameleaf Manager’s data. On HexOS, it’s the drive that holds your applications.
  • Manager can’t save in its own folder. The folder is read-only. Give Manager read and write access to it, as for any other folder above.

Port 2283 is in use means another app on this server is already using the port Frameleaf would open on. When Manager finds a free port, select Use port with that number. Otherwise, find the app using the port and stop it or change its port: in Unraid’s Docker tab, in TrueNAS Apps, in HexOS, or on plain Docker with sudo ss -ltnp.

Couldn’t check the port means Manager couldn’t test the port from here. If another app is using it, the install stops at that point and tells you.

A container setting can’t be used means one of your Advanced container settings won’t work. Go back, open Advanced container settings, and change or remove it.

Message What to do
Manager can’t reach Frameleaf’s downloads This server couldn’t connect to ghcr.io or github.com, where Frameleaf is downloaded from. Check the server is connected to the internet. If your network uses a VPN, DNS filter or ad blocker, allow ghcr.io and github.com.
This release doesn’t run on this server It has no build for this server’s processor. Go back and choose another release.
The release couldn’t be verified Manager checks every release’s signature before it installs anything, and this one didn’t pass. Go back and choose another release, or check again later.

This server has … of memory appears when faces and smart search are on and the server has less than 8 GB. Frameleaf will work, but faces and smart search can run out of memory. Select Turn off faces and smart search, or carry on and turn them off later if they struggle. Couldn’t check memory means Manager couldn’t tell how much memory the server has.

Frameleaf won’t be editable from Unraid’s Docker tab

Section titled “Frameleaf won’t be editable from Unraid’s Docker tab”

Frameleaf will still install and run. A folder Unraid uses to save its container settings isn’t connected to Manager. To fix it:

  1. In Unraid’s Docker tab, click Frameleaf and choose Edit.
  2. Choose Add another Path, Port, Variable, Label or Device, and set Config Type to Path.
  3. Set Container Path to /run/frameleaf-host/templates-user and Host Path to /boot/config/plugins/dockerMan/templates-user, then Apply.

Settings I changed in Docker or Unraid disappeared

Section titled “Settings I changed in Docker or Unraid disappeared”

Manager writes each container’s settings itself, and writes them again on every update, restore and library move, so a variable or folder added in Docker or Unraid’s Docker tab is removed. Before an update does that, Manager’s Overview shows … was changed in Docker or Unraid. Open Containers, choose Keep them here and save. To add settings that last, always use Containers.

If Docker itself fails later, while Manager installs or updates, the operation screen says what happened in plain words:

  • Port … is in use. Choose a different Frameleaf port, or stop the other app, then try again.
  • Folder missing. A folder Frameleaf uses isn’t on this server any more. Check its drive or share is connected and the folder wasn’t moved or renamed.
  • Too many downloads. Frameleaf’s download server is limiting downloads from this network for now. Wait an hour, then try again.
  • Manager can’t reach Frameleaf’s downloads. Check the internet connection, and allow ghcr.io, github.com and docker.io in any VPN, DNS filter or ad blocker.
  • Not enough room in Docker’s storage. Docker filled the drive that holds its images. Free some space, or remove images no container uses.

Then choose Resume safely to pick up where it left off.

Frameleaf warns you when the drive with your photos is nearly full, and when thumbnails on a drive of their own run low: The thumbnails drive is nearly full, then The thumbnails drive is almost out of space. When that drive fills, new thumbnails wait until there is room, and your photos are safe. Free some space on the drive, or move thumbnails to a bigger drive.

Manager’s Storage page marks a drive that’s Nearly full, and Services → Troubleshooting → Check connections checks each drive your library uses, with the photos, thumbnails, database and backups named on the drive that holds them. A drive with less than 5% or 2 GB left is nearly full. A folder only Docker reaches shows Manager can’t check free space on this folder from here. Frameleaf still uses it as normal.

If thumbnails are on a drive of their own and it’s unplugged, not mounted or failed, Frameleaf can’t start until it’s back. Your photos are safe. Reconnect the drive and select Check again on Manager’s Storage page, or put thumbnails back with your photos and make them again. See If the thumbnail drive goes missing.

Read its log with docker logs frameleaf_postgres. The usual causes:

  • data directory ... has wrong ownership: the database folder is on a filesystem without Unix ownership and permissions, such as NTFS or exFAT, or on a folder mounted from Windows into WSL. Move DB_DATA_LOCATION to a supported filesystem or a Docker volume. See Requirements.
  • Permission denied: the folder isn’t writable. On Unraid, this happens when DB_DATA_LOCATION is left at its default; see Unraid. On TrueNAS, check dataset permissions against the user used by the release’s database image; see TrueNAS.
  • A network share: the database must be on local storage. Network shares aren’t supported.

New installations have database checksums turned on. Check with:

Terminal window
docker exec -it frameleaf_postgres psql --dbname=postgres --username=<DB_USERNAME> --command="show data_checksums"

A result of on means they’re on. If so, check for checksum failures. A healthy database shows 0 for every row:

Terminal window
docker exec -it frameleaf_postgres psql --dbname=postgres --username=<DB_USERNAME> --command="SELECT datname, checksum_failures, checksum_last_failure FROM pg_stat_database WHERE datname IS NOT NULL"

You can also scan the database’s structure for errors:

Terminal window
docker exec -it frameleaf_postgres pg_amcheck --username=<DB_USERNAME> --heapallindexed --parent-check --rootdescend --progress --all --install-missing

A healthy result ends with every relation checked, such as 8832/8832 relations (100%), and exits with code 0.

If corruption is found:

  1. Stop Frameleaf and keep a copy of the current database files before you try any repair. A storage snapshot or offline copy is ideal. Leave the damaged pages in place rather than using settings that discard them to finish a dump.
  2. Restore the most recent healthy backup from before the corruption. See Backup and restore.
  3. Use the damaged dump to recover by hand anything changed since that backup, if you need to.

Corruption is most often caused by sudden power loss or unmounting, a database on a network share, or poor storage such as SD cards and failing disks.

  • A message that a worker is exiting is normal; idle workers shut down to save memory.
  • SIGKILL or exit code 137 means the process was killed. Check the host for an out-of-memory event or a manual stop, then adjust memory limits if needed. See Remote machine learning.
  • SIGILL or exit code 132 means your CPU isn’t compatible, usually because it lacks x86-64-v2 support. In a virtual machine, choose a CPU type that passes these instructions through. See Requirements.

Find the failed model in the machine learning log and the /cache mount in your installation. Stop machine learning, remove just the damaged model from the cache, then restart so it downloads again. Check the server can reach models.frameleaf.cloud, or the host set in MACHINE_LEARNING_MODEL_SOURCE_URL.

Faces, search or descriptions aren’t appearing

Section titled “Faces, search or descriptions aren’t appearing”

Processing runs in the background and can take a long time on a large library. Work through these:

  1. See how far it has got. Open Settings, then Computers & background work, then Background work. In Everyday, Features has a row for each feature, with its state, such as Running, Waiting, Paused, Up to date or Needs a look, and how many items are left.
  2. Read what went wrong. Switch to Advanced. Needs a look groups everything that failed by cause, such as The face and search helper didn’t answer or The original file is missing, with one thing to do about each. See Jobs and queues.
  3. Check it’s allowed to run now. If When heavy work runs is set to Overnight, heavy work waits for the night. A paused feature waits until you choose Resume.
  4. Check where it runs. Open Computers. A feature set to a computer that’s Not answering waits for it; nothing moves on its own. A feature set to Nowhere (keep this off) doesn’t run. See Choose processing for your hardware.
  5. Check the feature is on in Settings, then Search & intelligence.
  6. Catch up. In the menu at the end of a feature’s row, Catch up on what’s missing queues only the photos that haven’t been done. Do it all again… starts over for every photo.

New uploads and imports are worked on before older background work, so a big backlog doesn’t hold up today’s photos. For AI descriptions, follow the recommended setup order.

Open Background work, then Advanced. Needs a look says what went wrong first and how many photos it affects. Try again puts the failed work back once you’ve fixed the cause. Stop trying is for files Frameleaf can’t open; they’re kept as they are and no longer count as failed. Each task also says why it isn’t running, for example because it’s paused or waiting for the night.

When the cause is a missing or damaged file, Open Library care takes you to Damaged and missing files, where Frameleaf looks for a good copy by itself.

Read the failure Manager recorded, fix the cause, then choose Resume safely. Keep Manager’s own folder, the database folders and the original media folders as they are, and resume the same import instead of starting a second one. See Bring an existing library.

Manager lists my photo app but won’t let me choose it

Section titled “Manager lists my photo app but won’t let me choose it”

Manager says why under the app’s name: the database isn’t one it reads yet, the database container isn’t running, or the app keeps its photos in a Docker volume instead of a folder. See If an app can’t be chosen.

Manager says my version of the app hasn’t been tested

Section titled “Manager says my version of the app hasn’t been tested”

Imports from other photo apps are in Beta and work on a best-effort basis. Photos and albums should come across, and anything that can’t is listed before the import starts. Select Continue anyway, or cancel, upgrade the app and start again. See Versions that haven’t been tested.

The library opened but setup is still running

Section titled “The library opened but setup is still running”

That’s expected after an import. Frameleaf opens straight away and checks files, makes thumbnails and builds search in the background, in the Setting up your library bar. If the file check didn’t finish, select Check again. See While Frameleaf sets up your library.

The folder chooser only lists allowed folders. Imports, the imports folder inside Frameleaf’s storage folder, is always there: copy the export into it. To use another drive or share, add it in Manager with Used for set to Imports. A folder that shows No Google export found doesn’t hold the ZIP or .tgz files, or the unpacked Takeout folder. See Import from a folder on this server.

Frameleaf only sees the folders you connect to it. When the list is empty, the window says Frameleaf can’t see any folders here yet. In Frameleaf Manager, add your folder under External folders; Frameleaf restarts for a moment, then you can choose it. See Folders of photos.

The file is kept safe, backed up and downloadable; Frameleaf just can’t draw it yet. That’s normal for some cinema RAW video and for cameras newer than its decoders, and it never counts as damaged. See Supported formats.

Exports and scans often lose or change the date a photo was taken. Date & Time Doctor finds wrong dates, time zones and camera clocks, shows a preview, and fixes them with an undo.

Usually a reverse proxy limit. Allow large request bodies and long timeouts, and check the proxy’s free disk space. If you use a hosted proxy, check its current upload limit and your plan. See Reverse proxy and the FAQ.

“Server Status Offline” and “Version Unknown”

Section titled ““Server Status Offline” and “Version Unknown””

Check you can reach the server, and look for errors in the browser’s network tab. If pages load but live updates don’t, your reverse proxy needs to forward WebSockets. See Reverse proxy.

  • Check the address you typed, including http:// and the port :2283, from the phone’s browser.
  • Make sure the app and server versions are compatible. See Upgrading.
  • Away from home, you need remote access, a VPN or your own reverse proxy.
  • If the app asks for a 6-digit code, your account has two-step sign-in on. Enter the code from your authenticator app, or use a recovery code. See Two-step sign-in.
  • To see where and when your account signed in, open Account activity.
  • If the app says the certificate was refused, or that the secure connection failed with the selected client certificate, check that the client certificate is set for that exact server address, and that it hasn’t expired or been revoked on the proxy. On Android, also check it’s still installed in Android’s settings. See Servers behind a proxy on iPhone and iPad or Android.
  • If the app says the server or proxy refused access, the proxy wants headers or a certificate the app didn’t send. Check them in the server’s connection options, or ask your server’s administrator.
  • If the iPhone or iPad app says your server isn’t answering as a Frameleaf server, the address now reaches something else. Check that the address, your reverse proxy or your port forward still point at your Frameleaf server. Backup waits until it does, and nothing on the phone is lost.

Frameleaf runs best with Docker on Linux, so use that if you can. On Windows, run Docker through WSL 2, and keep the database on a Linux filesystem or a Docker volume, never on an NTFS folder. See Requirements.

If a test installation is beyond repair, see How do I wipe Frameleaf and start again?. This deletes everything, so keep it for test installations only.