Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Users lose the Podman socket after a reboot

Errorusers can't connect to podman.sock after reboot

Short answer

The Podman API socket is not a file you create. A systemd socket unit makes it. After a reboot it exists only if that unit is enabled, the user's systemd manager is running, and your tools point at the matching path. Enable podman.socket, turn on lingering, and set DOCKER_HOST.

  • Applies to Podman 5, systemd 255, Fedora 42 or Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check whether the rootless socket unit is active and whether the file exists.

    systemctl --user status podman.socket
    ls $XDG_RUNTIME_DIR/podman/podman.sock
  2. 2Match what you see, then jump to its fix

    1. 1systemctl --user is-enabled podman.socket prints disabledThe socket unit was started once but never enabledFix
    2. 2The socket works after you log in over SSH, but not for a service or a session that starts at bootThe user manager is not running because nobody is logged inFix
    3. 3The error shows a path that does not match the user the socket belongs toThe client points at the wrong socket pathFix

What does the error look like?

  • users can't connect to podman.sock after reboot
  • the rootless socket path $XDG_RUNTIME_DIR/podman/podman.sock does not exist

Cause 1 of 3

The socket unit was started once but never enabled

1Check

A unit that was only started does not come back at boot. The enabled state is what recreates it.

systemctl --user is-enabled podman.socket

2Fix

Enable and start it in one step. Socket activation then starts the Podman service the first time a client connects.

systemctl --user enable --now podman.socket

3Verify

The socket path exists.

ls $XDG_RUNTIME_DIR/podman/podman.sock

Confirmed by docs.podman.io

Did this fix it?

Cause 2 of 3

The user manager is not running because nobody is logged in

1Check

User units run inside a per-user systemd manager. Without lingering, it exists only while you are logged in, so right after a boot the socket unit is not active until you log in.

systemctl --user status podman.socket

2Fix

Turn on lingering. The user manager is then spawned at boot and kept after you log out, so enabled user units start on their own.

loginctl enable-linger $USER

3Verify

After the next reboot, the socket is active once you open a session, and the service that needs it no longer fails at boot.

systemctl --user status podman.socket

Confirmed by freedesktop.org

Did this fix it?

Cause 3 of 3

The client points at the wrong socket path

1Check

A rootless service listens on $XDG_RUNTIME_DIR/podman/podman.sock, for example /run/user/1000/podman/podman.sock. The rootful service uses /run/podman/podman.sock.

echo $DOCKER_HOST
id -u

2Fix

Set DOCKER_HOST for the rootless socket in the shell profile of the user who runs the tool, so Docker API clients such as docker-compose find it.

export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/podman/podman.sock

3Verify

Ask the API through the client.

docker ps

Confirmed by docs.podman.io

Did this fix it?

How do I stop it coming back?

  • Enable lingering once for every user that runs containers from services or timers.
  • Set DOCKER_HOST in the profile, not in a single terminal.
  • After changing user units, reboot a test machine once and confirm the socket without logging in first.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Related fixes

Servers

dnf cannot install MySQL on Amazon Linux 2023

dnf cannot find a mysql-server package on Amazon Linux 2023

Amazon Linux 2023 documents MariaDB, not MySQL, as its database server, with packages named mariadb105 and mariadb105-server.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.