Troubleshooting

Start here when something isn’t working. If you’re 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.

Useful Docker commands

See the containers

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

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

docker compose ps

Read the logs

docker logs frameleaf_server
docker logs frameleaf_machine_learning
docker logs frameleaf_postgres
docker logs frameleaf_redis

Add --follow to keep streaming new lines, which is handy while you reproduce a problem. Service-based commands work whatever the containers are called:

docker compose logs immich-server
docker compose logs --follow immich-machine-learning

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

Open a shell in a container

docker exec -it frameleaf_server bash
docker exec -it frameleaf_machine_learning bash

Run server commands

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

The older immich-admin name still works as an alias. See Server commands.

Installation problems

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

Errors such as unknown shorthand flag: 'd' in -d or open <path to .env>: permission denied mean the Docker package from your distribution is incomplete or too old (this happens with the docker.io package on Ubuntu 22.04, for example). 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-’”

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”

The full message is can't set healthcheck.start_interval as feature require Docker Engine v25 or later. Update Docker, or comment out the start_interval line in the database service of docker-compose.yml. This is common on Unraid 6.12; see Unraid.

I can’t open the web app

1. Check all four 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 a Synology, check the firewall rules, which break when the container’s IP address changes.
4. If you use a reverse proxy, try the direct address first to rule it out. See Reverse proxy.

The setup code is rejected

• The code changes every time the server starts. Get the current one with docker exec -it frameleaf_server frameleaf-admin setup-code.
• After 5 wrong tries the server issues a new code. Check the log again.
• A new server can only be set up from its home network. Open the web app from a device on the same network, not through a tunnel or proxy on the internet.

Database problems

The database container keeps restarting

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

• data directory "/var/lib/postgresql/data" 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, the pgData dataset must be owned by netdata (UID 999); see TrueNAS.
• A network share: the database must be on local storage. Network shares aren’t supported.

Check the database for corruption

New installations have database checksums turned on. Check with:

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:

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:

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. Make a backup straight away, before you do anything else. You may need to set zero_damaged_pages=on on the database server for pg_dumpall to succeed.
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.

Machine learning problems

Workers crash

• A message that a worker is exiting is normal; idle workers shut down to save memory.
• SIGKILL or exit code 137 means the container ran out of memory. Add memory or move machine learning to a computer with more. 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.

Models won’t download or are corrupt

Delete the model cache volume (immich_model-cache with the default project name) and restart the machine learning container so the models download 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

Processing runs in the background and can take a long time on a large library. Open Settings, then Compute & jobs to see what’s queued, and check the machine learning logs for errors. Make sure the feature is turned on in Administration, then Settings, then Machine Learning. For AI descriptions, follow the recommended setup order.

Upload and connection problems

Large uploads or videos fail

Usually a reverse proxy limit. Allow large request bodies and long timeouts, and check the proxy’s free disk space. Cloudflare Tunnel limits uploads to 100 MB. See Reverse proxy and the FAQ.

“Server Status Offline” and “Version Unknown”

Your reverse proxy isn’t passing WebSockets. See Reverse proxy.

The phone app can’t connect or sign in

• 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.

Running on Windows

Running Frameleaf on Windows can be frustrating, and there are many ways it can go wrong. Use Docker on Linux if you can. If you use 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.

Start again from scratch

If a test installation is beyond repair, see How do I wipe Frameleaf and start again?. This deletes everything, so never do it on a library you care about.