Podman Container Startup Stuck? It Might Be Network-Online.target Causing Trouble

Problem Symptoms

Have you ever encountered situations where podman commands get stuck for a long time without any output when starting containers, and can’t proceed to the next step? This is especially common when using systemd or Quadlet to manage container lifecycles, for example, when executing systemctl --user start my-container.service, the command gets stuck until a 90-second timeout.

This issue has been discussed in the community, such as the network-related problems mentioned in Podman GitHub Issue #24796, which can all lead to similar phenomena.

Root Cause

The root of this problem usually lies not in podman itself, but in the interaction mechanism between podman and systemd, particularly regarding network dependencies.

When you use Quadlet (files with suffixes like .container, .kube, .volume, etc.) to create systemd services for managing containers, the generated service units typically include a dependency: After=network-online.target.

network-online.target is a special target in systemd that indicates the system’s network is fully configured and accessible. Many services that require network connectivity (such as databases, web services, and our containers) wait for this target to be achieved before starting, to ensure the network is available.

However, in certain Linux distributions or specific network configurations, the components responsible for managing the network (such as NetworkManager or systemd-networkd) may not correctly notify systemd that the network is “online”. This causes network-online.target to never be activated, and all services dependent on it (including your Podman container services) will wait indefinitely, creating the illusion of being “stuck”.

Solutions

For this issue, there are currently two effective solutions you can choose from based on your situation.

Method 1: Modify Quadlet Files

If you confirm that your container doesn’t need to wait for the network to be fully ready before starting (for example, the container doesn’t immediately provide external services, or the service itself has retry mechanisms), you can directly disable the default network dependency in your .container file.

In the corresponding Quadlet file (such as ~/.config/containers/systemd/my-container.container), add the following section:

[Quadlet]
DefaultDependencies=false

This configuration tells Quadlet not to automatically add the After=network-online.target dependency when generating systemd service files.

After modification, you need to reload the systemd configuration for the changes to take effect:

systemctl --user daemon-reload

After that, you can normally start your container service, and it will no longer wait for network-online.target.

The advantage of this method is that it only affects specific containers and is persistent, requiring no manual intervention after each restart.

Method 2: Manually Trigger network-online.target

If you urgently need to start the container or don’t want to modify Quadlet files, you can manually trigger network-online.target. Run the following command in the terminal:

sudo systemctl start network-online.target

This command manually marks network-online.target as activated, thereby unblocking all services waiting for this target, and your Podman container service will be able to start smoothly.

However, this is only a temporary measure, and you may need to manually execute it again after each system restart.

Discussion on Global Solutions

Some users try to automatically handle this dependency by enabling NetworkManager-wait-online.service with the following command:

# Note: This method is not reliable according to community feedback
sudo systemctl enable NetworkManager-wait-online.service

However, according to ongoing discussions in related GitHub Issues, this method is not stable, and the problem persists in many scenarios. Therefore, the podman community has not yet closed related issues and is still actively seeking more reliable fundamental solutions.

Summary

Podman container startup getting stuck is usually due to the network-online.target that its systemd service depends on not being activated. Until the official provides a more perfect global solution, these two methods are the most reliable choices. I hope this article can help you solve this confusing problem.