🦭 Podman Error: 'pod already exists' on podman pod create

Exact Error Message

$ podman pod create --name web-stack -p 8080:8080
Error: adding pod to state: name "web-stack" is in use: pod already exists

The same conflict surfaces differently when a manifest is being replayed:

$ podman kube play web-stack.yaml
Error: pod web-stack already exists: pod already exists

What It Means

A pod in Podman is a shared namespace group plus a small “infra” container that holds the network and IPC namespaces open so the real workload containers can join them. Pods are tracked in a per-user state database — the BoltDB/SQLite store under the graph root — and pod names are unique keys in that store. pod already exists means the store already has an entry with that name, regardless of whether any of its containers are currently running.

That last point is the source of most confusion. A pod whose containers all exited, or whose infra container was killed out from under it, still occupies its name. podman pod ls without flags shows pods in all states, but podman ps does not, so a stopped pod is easy to miss when you are only looking at running containers. The store is also per-user and per-privilege-level: root Podman writes under /var/lib/containers/storage while your rootless user writes under ~/.local/share/containers/storage. A pod created by a system service is completely invisible to your podman pod ls, and vice versa.

Common Causes

• A previous pod with that name was stopped but never removed, so it still holds the name.
• A Quadlet-generated or hand-written systemd unit recreated the pod on boot and left it behind after a failed restart.
• podman kube play was re-run without --replace, and the manifest’s metadata.name collides with the existing pod.
• A CI job or script creates the pod without checking existence first, and the previous run’s cleanup step failed.
• You are looking at the rootless store while the conflicting pod lives in the root store (or the reverse).
• The infra container was removed manually, leaving a degraded pod entry that still occupies the name.

Diagnostic Commands

List every pod including stopped ones, with the infra container ID so you can see whether the pod is intact:

podman pod ls -a
podman pod ls --format '{{.Name}}\t{{.Status}}\t{{.NumberOfContainers}}\t{{.InfraID}}'

Inspect the conflicting pod to see when and how it was created:

podman pod inspect web-stack --format '{{.Created}} {{.State}}'
podman pod inspect web-stack | jq '{Name, State, Containers: [.Containers[].Name]}'

Check whether the conflict is in a different store. Run the identical query as root:

sudo podman pod ls -a
podman info --format '{{.Store.GraphRoot}}'
sudo podman info --format '{{.Store.GraphRoot}}'

Find out whether systemd is recreating the pod behind your back — this is the usual cause of a pod that reappears after you delete it:

systemctl --user list-units 'podman*' '*-pod.service'
systemctl --user cat web-stack-pod.service 2>/dev/null
ls -l ~/.config/containers/systemd/

For scripts, podman pod exists is the right probe. It prints nothing and signals purely through its exit code — 0 when the pod exists, 1 when it does not:

podman pod exists web-stack && echo "present" || echo "absent"

Step-by-Step Resolution

1. Confirm the pod really exists and look at its state before deleting anything:

podman pod ls -a --filter name=web-stack

2. If it is stale, remove it. -f stops and removes the member containers along with the infra container:

podman pod rm -f web-stack
podman pod create --name web-stack -p 8080:8080

3. For repeatable scripts and CI, use --replace so creation is idempotent rather than racing a cleanup step:

podman pod create --replace --name web-stack -p 8080:8080

4. For manifests, podman kube play has its own replace flag, and a --down teardown for the explicit case:

podman kube play --replace web-stack.yaml
podman kube play --down web-stack.yaml

5. If systemd owns the pod, stop the unit before touching it by hand — otherwise the unit will simply recreate it:

systemctl --user stop web-stack-pod.service
systemctl --user disable web-stack-pod.service
podman pod rm -f web-stack

6. Guard your provisioning scripts with the exit-code probe so re-runs are safe:

#!/usr/bin/env bash
set -euo pipefail
if podman pod exists web-stack; then
  podman pod rm -f web-stack
fi
podman pod create --name web-stack -p 8080:8080

If the pod refuses to remove because a member container is wedged, remove the container directly first, then retry the pod removal:

podman ps -a --pod --filter pod=web-stack
podman rm -f <container-id>
podman pod rm -f web-stack

Prevention

• Always use --replace on podman pod create in scripts and CI rather than assuming a clean slate.
• Prefix pod names per environment or per CI job ID so parallel runs cannot collide.
• Let Quadlet units own their pods exclusively; do not create the same pod by hand as well.
• Add a teardown step (podman pod rm -f or kube play --down) to the failure path of every job, not just the success path.
• Be explicit about privilege: document whether a service runs rootless or as root, since the two stores are separate namespaces.
• Use podman pod exists as a precondition check instead of parsing podman pod ls output.

Related Errors

• Error: creating container storage: the container name "web" is already in use — the same uniqueness rule at container rather than pod level.
• Error: cannot listen on the TCP port: bind: address already in use — a port conflict from the old pod’s infra container still holding the socket.
• Error: no such pod — the opposite condition; you are querying the other store or the pod was already removed.
• Error: unsupported compose file version — a different orchestration path entirely. See compose file not supported.

Frequently Asked Questions

Why does the pod exist when podman ps shows nothing? podman ps lists running containers only. A pod whose containers have all exited is still registered in the state store and still owns its name. Use podman pod ls -a to see it.

What is the infra container and can I delete it? It is the small pause container that holds the pod’s shared network and IPC namespaces open. Deleting it directly leaves the pod degraded but still occupying the name — remove the whole pod with podman pod rm -f instead.

Why does the pod reappear after I remove it? A systemd unit, usually generated from a Quadlet file in ~/.config/containers/systemd/, is recreating it. Stop and disable the unit before removing the pod by hand.

Do root and rootless pods conflict with each other? No. They use entirely separate storage and state, so the same pod name can exist in both simultaneously — which is exactly why sudo podman pod ls sometimes shows a pod your own podman pod ls does not. Related rootless pitfalls are covered in rootless overlay storage and the Podman guides.