How to Troubleshoot Root Login Issues on Immich Self-Hosted Servers

Root login problems on an Immich self-hosted server can appear in several different ways. An administrator may be unable to sign in to the Linux host as root, may be blocked from accessing a Docker container as root, may have trouble reaching PostgreSQL, or may be confusing the Immich web application’s first admin account with the operating system’s root account. Because Immich is usually deployed with Docker Compose, troubleshooting requires looking at the host system, containers, environment files, logs, reverse proxy, database, and authentication settings together.

TLDR: Immich does not usually rely on a traditional “root login” inside the web interface; its primary login is the app’s admin or user account. If root access to the server is failing, the administrator should verify SSH configuration, Linux permissions, sudo access, and firewall rules. If Immich login is failing, they should inspect Docker containers, .env values, database connectivity, logs, and proxy settings. The safest troubleshooting path is to confirm which “root” account is affected before changing passwords or rebuilding containers.

Understanding What “Root Login” Means in an Immich Setup

Before any fix is attempted, the administrator should identify which layer is actually failing. In a self-hosted Immich installation, the word root may refer to several different things:

• Linux root user: The privileged account on the server operating system.
• SSH root login: Remote login as root over SSH.
• Docker container root: Accessing a container shell as the root user.
• PostgreSQL superuser: The database administrator account, often confused with root.
• Immich admin account: The first user created in the Immich web interface, which is not the same as Linux root.

This distinction matters because resetting the Linux root password will not fix a forgotten Immich admin password, and changing an Immich user will not restore SSH access. A careful administrator should define the failure first: Is the server refusing SSH, is Docker inaccessible, or is the Immich web login rejected?

Checking Linux Root or SSH Login Problems

If the issue is that the administrator cannot log in to the server as root, the first area to inspect is SSH. Many modern Linux distributions disable direct root SSH login by default for security reasons. This is normal and often recommended. Instead, a regular user logs in and runs privileged commands with sudo.

The SSH daemon configuration is usually stored at:

/etc/ssh/sshd_config

The administrator can inspect the following settings:

PermitRootLogin no
PasswordAuthentication no
PubkeyAuthentication yes

If PermitRootLogin is set to no, direct root login is intentionally disabled. If it is set to prohibit-password, root may log in only with an SSH key, not with a password. After any legitimate configuration change, SSH should be restarted carefully:

sudo systemctl restart ssh
# or
sudo systemctl restart sshd

Before closing the existing terminal session, the administrator should always test a second login window. This prevents accidental lockout if the SSH configuration contains an error.

Verifying Sudo Access

In many Immich deployments, root login is unnecessary if the administrator has sudo privileges. The following command confirms whether the current user can run administrative commands:

sudo -v

If the user is not in the correct sudo group, the system may return an error such as “user is not in the sudoers file.” On Debian and Ubuntu systems, the administrator account is typically added to the sudo group. On some other distributions, the group may be wheel.

When server console access is available through a hosting provider, the root password or sudo privileges can often be repaired from a rescue console. If no privileged access remains, recovery may require booting into single-user mode, using the cloud provider’s recovery tools, or mounting the disk on another instance.

Confirming Docker Permissions

Immich normally runs through Docker Compose. A common issue occurs when the administrator can access the server but cannot run Docker commands. The error may look like this:

permission denied while trying to connect to the Docker daemon socket

This does not necessarily mean root login is broken. It usually means the current Linux user lacks permission to control Docker. The administrator can test Docker with:

sudo docker ps

If that works, Docker itself is running. To allow a non-root user to run Docker commands, the account can be added to the Docker group:

sudo usermod -aG docker username

Afterward, the user must log out and log back in for the group membership to apply. However, membership in the Docker group is highly privileged. It is effectively equivalent to root access, so it should be granted only to trusted administrator accounts.

Inspecting Immich Container Status

If the login issue is inside the Immich web interface, the administrator should check whether all required containers are healthy. From the directory containing the Immich docker-compose.yml file, this command is useful:

docker compose ps

The main services usually include the Immich server, machine learning service, Redis, and PostgreSQL. If the Immich server or database is restarting repeatedly, login will fail even if the credentials are correct.

Logs should be reviewed next:

docker compose logs immich-server
docker compose logs database
docker compose logs redis

Authentication failures, database connection errors, missing environment variables, or migration problems often appear clearly in these logs. The administrator should look for messages relating to password authentication failed, connection refused, JWT, database, or migration.

Reviewing the Immich Environment File

Immich deployments use environment variables, usually stored in a .env file. Incorrect values in this file can prevent the application from connecting to PostgreSQL or generating valid sessions.

The administrator should confirm values such as:

• DB_HOSTNAME
• DB_USERNAME
• DB_PASSWORD
• DB_DATABASE_NAME
• REDIS_HOSTNAME
• UPLOAD_LOCATION

If the database password in .env does not match the actual PostgreSQL password, Immich may start partially or fail during authentication-related operations. The administrator should avoid randomly changing these values without confirming the current database state, because mismatched credentials can make the situation worse.

Distinguishing Immich Admin Login from Root Login

The Immich web interface does not use Linux’s root account. During initial setup, Immich asks for the creation of an admin user. That account is stored in the Immich database and is managed by the application, not by the operating system.

If the administrator can reach the Immich web page but cannot sign in, the likely causes include:

• Wrong email address or password: The Immich login uses the registered account email.
• Database connection failure: The account cannot be verified if PostgreSQL is unavailable.
• Reverse proxy cookie issues: Incorrect HTTPS, headers, or domain configuration can break sessions.
• OAuth or external authentication changes: A misconfigured identity provider may block login.
• Version mismatch: Containers from different Immich versions may cause unexpected behavior.

When possible, the administrator should compare the Immich server version, web version, and Compose file version. Immich evolves quickly, and older configuration examples may not match newer releases.

Checking Database Access

PostgreSQL is central to Immich authentication. If the database is unavailable, corrupted, or using the wrong password, login may fail. The administrator can enter the database container with a command similar to:

docker exec -it immich_postgres psql -U postgres

The exact container name and username may differ depending on the Compose file. If that command fails, the administrator should inspect the database container name with:

docker ps

Database troubleshooting should be performed carefully. Direct edits to Immich tables can damage the application if done incorrectly. Before any manual database change is considered, a complete backup should be created. A safer first step is to confirm that PostgreSQL is running, that credentials match the .env file, and that Immich migrations completed successfully.

Investigating Reverse Proxy and HTTPS Issues

Many self-hosted Immich servers are placed behind Nginx Proxy Manager, Traefik, Caddy, Apache, Cloudflare Tunnel, or another reverse proxy. In those cases, login problems may be caused by the proxy rather than Immich itself.

Symptoms of proxy-related problems include a successful login followed by an immediate logout, endless redirects, blank pages, failed API calls, or mobile app authentication failures. The administrator should verify that the proxy forwards the correct headers, supports large uploads, and uses the proper scheme.

Important headers commonly include:

• X-Forwarded-For
• X-Forwarded-Proto
• X-Real-IP
• Host

If HTTPS is terminated at the proxy, Immich must still receive correct information about the original secure request. Otherwise, session cookies may not behave as expected.

Reviewing File and Volume Permissions

Immich stores uploads, thumbnails, encoded videos, profile images, and other assets in mounted volumes. If the server’s file permissions are wrong, Immich may behave unpredictably. Authentication itself may still work, but the application can fail soon after login or display errors that appear related to account access.

The administrator should inspect ownership and permissions for the upload directory:

ls -la /path/to/immich/upload

Changing permissions broadly with commands such as chmod 777 is not recommended. It may temporarily hide the problem while creating serious security risks. Instead, permissions should match the user and group expected by the Immich containers and the deployment documentation.

Considering Updates and Version Mismatches

Immich updates frequently, and login problems can appear after partial upgrades. A common mistake is updating only one container image while leaving other services, Compose definitions, or environment variables outdated.

A routine update generally includes pulling current images and restarting services:

docker compose pull
docker compose up -d

However, the administrator should read the release notes before upgrading, especially when moving across major versions or when authentication, database, or storage changes are mentioned. Backups should be created before updates, not after a failure occurs.

Using Logs to Identify Authentication Failures

Logs are among the most reliable troubleshooting tools. Instead of guessing whether the problem is root, Docker, database, or Immich-related, the administrator should observe the logs while attempting a login:

docker compose logs -f immich-server

Then, during a fresh login attempt, any errors can be matched to the exact time of failure. A password error, database refusal, token problem, OAuth callback failure, or proxy issue will usually leave a trace. This method reduces unnecessary changes and helps prevent destructive fixes.

Security Best Practices During Troubleshooting

Root access should be handled conservatively. Enabling direct root SSH login with passwords may solve an immediate access problem, but it also increases exposure to brute-force attacks. A better approach is usually to keep direct root login disabled, use SSH keys, maintain a sudo-capable admin account, and protect SSH with firewall rules or VPN access.

For Immich itself, strong passwords, HTTPS, updated containers, and regular backups are essential. If the administrator suspects a compromised account, they should rotate passwords, review users, check proxy access logs, and confirm that no unknown SSH keys or administrator accounts have been added to the host.

A Practical Troubleshooting Checklist

• Confirm whether the issue affects Linux root, Docker, PostgreSQL, or the Immich web admin.
• Check SSH settings in /etc/ssh/sshd_config.
• Verify that a normal administrator account has working sudo access.
• Run docker compose ps to confirm container health.
• Review Immich, Redis, and PostgreSQL logs.
• Validate database credentials in the .env file.
• Check reverse proxy headers, HTTPS, and cookie behavior.
• Inspect upload volume permissions.
• Confirm that all Immich containers are on compatible versions.
• Create backups before resetting passwords, editing the database, or rebuilding volumes.

FAQ

Does Immich have a Linux root login?

No. Immich’s web login is separate from the Linux root account. The first Immich admin user is stored in the application database and does not control operating system access.

Why can the administrator not SSH into the server as root?

Direct root SSH login may be disabled in /etc/ssh/sshd_config. Many systems require login through a normal user account followed by sudo.

Can Docker be managed without logging in as root?

Yes. Docker commands can be run with sudo, or the administrator account can be added to the Docker group. However, Docker group access is highly privileged and should be limited.

What should be checked if the Immich admin password does not work?

The administrator should verify the correct email address, inspect Immich server logs, confirm PostgreSQL connectivity, review proxy settings, and ensure that the deployment was not partially upgraded.

Can the Immich database be edited to fix a login issue?

Direct database edits are risky and should only be considered after a full backup. In most cases, logs, environment variables, container health, and proxy configuration should be checked first.

Why does Immich log in and then immediately log out?

This often points to reverse proxy, HTTPS, cookie, or forwarded header problems. The administrator should verify proxy configuration and confirm that Immich receives the correct protocol and host information.

Should direct root SSH login be enabled permanently?

Usually not. A safer configuration uses SSH keys, disables password-based root login, relies on sudo-capable administrator accounts, and restricts access with firewall or VPN controls.