🦭 Podman Error: 'short-name did not resolve to an alias and no unqualified-search-registries are defined' on Build or Pull

Exact Error Message

$ podman build -t myapp .
STEP 1/6: FROM ubuntu:22.04
Error: creating build container: short-name "ubuntu:22.04" did not resolve to an alias and no unqualified-search-registries are defined in "/etc/containers/registries.conf"

The same failure appears on a plain pull:

$ podman pull nginx
Error: short-name resolution enforced but cannot prompt without a TTY

What It Means

Unlike Docker, Podman does not silently assume docker.io for an image reference that has no registry. When you write FROM ubuntu:22.04 or podman pull nginx, the reference is a short name — it has no registry hostname, so Podman has to decide which registry to contact. It resolves that in two steps: first it checks the alias table (a map of short names to fully qualified references), and if there is no alias it walks the unqualified-search-registries list from registries.conf, trying each registry in order. If the alias table has no entry and the search list is empty, there is nothing left to try and Podman fails with this error rather than guessing.

The second variant is the same problem in a different mode. Podman’s short-name-mode controls what happens when a short name matches images in multiple search registries: in enforcing mode it prompts you to choose, and records your choice as an alias. A prompt requires a TTY. In CI, in a systemd unit, or under podman build invoked from a script, there is no terminal to answer, so the enforcing prompt turns into a hard error. Both messages are Podman refusing to make an ambiguous network decision on your behalf, and both are fixed in configuration rather than on the command line.

Common Causes

• /etc/containers/registries.conf has an empty or missing unqualified-search-registries list — common on minimal, distroless-ish, or container-in-container base images.
• A drop-in file in /etc/containers/registries.conf.d/ overrides the distro default with an empty list; later files win lexically.
• The shortnames alias table at /etc/containers/registries.conf.d/000-shortnames.conf was removed with the containers-common package or masked by a config-management run.
• short-name-mode = "enforcing" in a non-interactive context (CI runner, systemd, podman build in a pipeline) where the disambiguation prompt cannot be answered.
• A rootless user has ~/.config/containers/registries.conf, which replaces the system file rather than merging with it, silently dropping the search list.
• Building inside a container image that ships its own stripped registries.conf for the nested Podman.

Diagnostic Commands

Start by asking Podman what it actually loaded — this reads the merged configuration, not just the base file:

podman info --format '{{.Registries}}'
podman info --format '{{.Store.ConfigFile}}'

Dump the effective registry configuration and every drop-in contributing to it:

cat /etc/containers/registries.conf
ls -l /etc/containers/registries.conf.d/
grep -rn 'unqualified-search-registries\|short-name-mode' /etc/containers/registries.conf /etc/containers/registries.conf.d/

For rootless, check whether a per-user file is shadowing the system one:

ls -l ~/.config/containers/registries.conf
grep -rn 'unqualified-search-registries' ~/.config/containers/ 2>/dev/null

Confirm the alias table is present and contains the name you are pulling:

grep -n '"ubuntu"\|"nginx"' /etc/containers/registries.conf.d/000-shortnames.conf

Finally, prove that the image itself is reachable by bypassing short-name resolution entirely:

podman pull docker.io/library/ubuntu:22.04

If that succeeds, the registry and your credentials are fine and the problem is purely name resolution. If it fails with an auth message instead, see Podman image pull unauthorized.

Step-by-Step Resolution

1. The quickest unblock — and the best long-term habit — is to fully qualify the reference. FROM ubuntu is ambiguous; FROM docker.io/library/ubuntu is not:

FROM docker.io/library/ubuntu:22.04
RUN apt-get update && apt-get install -y ca-certificates

2. Define a search list system-wide so existing short names resolve. Prefer a drop-in over editing the base file so package upgrades do not clobber it:

sudo tee /etc/containers/registries.conf.d/010-search.conf >/dev/null <<'EOF'
unqualified-search-registries = ["docker.io", "quay.io", "registry.access.redhat.com"]
EOF

3. Set short-name-mode so non-interactive builds never hit a prompt. permissive still uses aliases and the search list but falls back silently instead of prompting; disabled skips the alias table checks entirely:

sudo tee -a /etc/containers/registries.conf.d/010-search.conf >/dev/null <<'EOF'
short-name-mode = "permissive"
EOF

4. Restore or extend the alias table if you want deterministic mapping regardless of search order. Entries live under the [aliases] section:

sudo dnf reinstall -y containers-common   # or: sudo apt-get install --reinstall containers-common
sudo tee /etc/containers/registries.conf.d/020-local-aliases.conf >/dev/null <<'EOF'
[aliases]
  "ubuntu" = "docker.io/library/ubuntu"
  "myapp"  = "registry.internal.example.com/team/myapp"
EOF

5. For rootless, remember that ~/.config/containers/registries.conf replaces the system file. Either delete it or make it self-contained:

mkdir -p ~/.config/containers
tee ~/.config/containers/registries.conf >/dev/null <<'EOF'
unqualified-search-registries = ["docker.io", "quay.io"]
short-name-mode = "permissive"

[[registry]]
prefix = "docker.io"
location = "mirror.internal.example.com/dockerhub"
EOF

6. Re-run the build and confirm resolution. Adding --log-level=debug shows the exact registry Podman selected:

podman build --log-level=debug -t myapp . 2>&1 | grep -i 'short-name\|resolved'
podman build -t myapp .

For generating registry mirror blocks and per-environment registries.conf drop-ins, the Podman prompts in the prompt library can produce a reviewed configuration for your registry topology.

Prevention

• Fully qualify every image reference in Dockerfiles, Containerfiles, and Kubernetes YAML; short names are convenience, not contract.
• Ship registries.conf drop-ins through configuration management so CI runners and workstations agree.
• Never set short-name-mode = "enforcing" on an image or host used for automated builds.
• Keep containers-common installed so 000-shortnames.conf survives package upgrades and image rebuilds.
• Use [[registry]] prefix/location pairs to point at a pull-through mirror rather than rewriting every reference.
• Add a podman pull smoke test of one fully qualified and one short name to your image-build CI so config drift fails fast.

Related Errors

• short-name resolution enforced but cannot prompt without a TTY — the name is ambiguous and short-name-mode = "enforcing" wants to prompt, but there is no terminal to prompt on. That is the CI and systemd variant of this same resolution problem; see short-name resolution enforced but cannot prompt without a TTY.
• unauthorized: authentication required — resolution worked and the registry was reached, but credentials are missing; see image pull unauthorized.
• manifest unknown — the registry resolved correctly but that tag does not exist on it.
• pinging container registry: dial tcp: i/o timeout — a search registry in the list is unreachable and Podman is waiting on it.
• error creating build container: no such file or directory — a storage-driver problem rather than name resolution; see fuse-overlayfs not found.

Frequently Asked Questions

Why does this work on Docker but not Podman? Docker hardcodes Docker Hub as the implicit registry for short names. Podman deliberately does not, because it is registry-agnostic and treats an unqualified name as under-specified. Fully qualifying the reference makes the behavior identical everywhere.

What is the difference between the alias table and unqualified-search-registries? The alias table maps one exact short name to one exact fully qualified reference, so resolution is deterministic. The search list is a fallback that tries registries in order and can match different images on different hosts. Aliases win when both are present.

Should I use permissive or disabled for short-name-mode? Use permissive for CI: aliases and the search list still apply, but ambiguity resolves silently instead of prompting. Use disabled only if you want the alias table ignored entirely and to rely solely on the search list.

Why did my rootless user break after I fixed the system file? ~/.config/containers/registries.conf replaces /etc/containers/registries.conf rather than merging with it. Remove the user file, or duplicate the search list and mode into it. For more container fixes, see the Podman guides.