🦭 Podman Error: 'short-name resolution enforced but cannot prompt without a TTY' in CI and Systemd

Exact Error Message

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

The same failure surfaces during a build when the base image in a FROM line is unqualified:

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

What It Means

A short name is an image reference that omits the registry host, like nginx, python:3.12-slim, or quay.io-less fedora. Unlike Docker, Podman does not silently assume Docker Hub. It resolves short names through the configuration in /etc/containers/registries.conf and any drop-in files under /etc/containers/registries.conf.d/, using either a hard-coded alias table or the unqualified-search-registries list. When more than one candidate registry could match, Podman’s default short-name-mode = "enforcing" refuses to guess and instead prompts you interactively to pick one.

That prompt requires a terminal. In CI runners, systemd units, cron jobs, Ansible tasks, and anything driven through podman --remote or a pipe, there is no TTY to draw the menu on, so Podman aborts with cannot prompt without a TTY. The error is therefore not really about the missing terminal — it is telling you that the image reference is ambiguous and the machine has no way to disambiguate it. The fix is to make the reference unambiguous, either by writing a fully-qualified name or by teaching Podman a deterministic mapping.

Common Causes

• The image reference is a short name (nginx, redis:7) and short-name-mode is left at its default enforcing.
• unqualified-search-registries lists two or more registries, so the resolution is genuinely ambiguous.
• unqualified-search-registries is empty or missing entirely, so nothing can resolve the name at all.
• A Containerfile copied from a Docker workflow uses FROM ubuntu:22.04 with no registry prefix.
• The command runs from a systemd unit, Quadlet, cron entry, or CI job where stdin is not a terminal.
• A rootless user has a ~/.config/containers/registries.conf that shadows the system file and drops the search list.

Diagnostic Commands

Show the effective registry configuration Podman is actually loading, including drop-ins:

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

Inspect the merged configuration file set and the current mode:

grep -rn "short-name-mode\|unqualified-search-registries" \
  /etc/containers/registries.conf /etc/containers/registries.conf.d/ \
  ~/.config/containers/registries.conf 2>/dev/null

Ask Podman to resolve the name without pulling anything, which prints the candidates it would try:

podman image search --limit 5 nginx

Confirm whether the failure is TTY-related by forcing a terminal and seeing if a menu appears:

podman pull nginx < /dev/tty

List any short-name aliases already defined on the host:

cat /etc/containers/registries.conf.d/*.conf

Step-by-Step Resolution

1. The correct long-term fix is to use fully-qualified image names everywhere. Replace the short reference in your command or Containerfile:

podman pull docker.io/library/nginx:latest

FROM docker.io/library/python:3.12-slim

2. If you control the host and want short names to work deterministically, add a single unqualified search registry so there is exactly one candidate:

# /etc/containers/registries.conf
unqualified-search-registries = ["docker.io"]

3. For teams that pull from more than one registry, keep the search list ambiguous but define explicit aliases in a drop-in file. Aliases always win over the search list:

# /etc/containers/registries.conf.d/999-local-aliases.conf
[aliases]
  "nginx"           = "docker.io/library/nginx"
  "python"          = "docker.io/library/python"
  "ubi9"            = "registry.access.redhat.com/ubi9/ubi"
  "internal-base"   = "registry.corp.example.com/platform/base"

4. If you cannot edit images or add aliases immediately, relax the mode so Podman picks the first matching search registry instead of prompting:

# /etc/containers/registries.conf
short-name-mode = "permissive"

Use "disabled" only if you also want to suppress the warning Podman logs when it auto-resolves; "enforcing" remains the safest setting for production hosts because it prevents a typo’d name from silently resolving to an attacker-controlled registry.

5. For a rootless user, remember the per-user file overrides the system one entirely — it is not merged field by field. Either delete it or mirror the system settings into it:

mkdir -p ~/.config/containers
cp /etc/containers/registries.conf ~/.config/containers/registries.conf
podman info --format '{{ .Registries }}'

6. Re-run the original command and confirm the pull completes non-interactively, exactly as CI would:

podman pull docker.io/library/nginx:latest < /dev/null
podman images

If the same unit still fails after this, the problem has moved elsewhere in the rootless stack — check for user-namespace setup failures such as Podman error: cannot set up namespace using newuidmap: exit status 1, which also tends to appear only under systemd.

Prevention

• Write fully-qualified image names in every Containerfile, Compose file, and Quadlet unit; treat short names as a local-shell convenience only.
• Ship /etc/containers/registries.conf.d/ drop-ins through configuration management so every builder and runner resolves names identically.
• Keep short-name-mode = "enforcing" in production and rely on aliases rather than downgrading to permissive.
• Add a CI lint step that greps Containerfile for FROM lines without a /-separated registry host.
• Avoid per-user ~/.config/containers/registries.conf files unless you deliberately want to override the whole system config.
• Mirror third-party base images into an internal registry and alias the short names to it, so pulls stay reproducible.

Related Errors

• short-name "x" did not resolve to an alias and no unqualified-search registries are defined — the search list is empty rather than ambiguous; add a registry or a fully-qualified name. See short-name did not resolve to an alias.
• Error: initializing source docker://nginx:latest: pinging container registry — resolution succeeded but the network or TLS handshake to the registry failed.
• Error: unable to pull image: manifest unknown — the name resolved correctly but that tag does not exist in the chosen registry.
• Error: authentication required — the registry was resolved but no credentials are present in ${XDG_RUNTIME_DIR}/containers/auth.json.

Frequently Asked Questions

Why does this only break in CI when it works on my laptop? Your interactive shell has a TTY, so enforcing mode draws a selection menu you answer without thinking about it. CI runners, systemd services, and cron have no terminal, so the same ambiguous name becomes a hard failure. Fully-qualified names behave identically in both environments.

Is short-name-mode = "permissive" safe? It is convenient but weakens a real protection. With multiple search registries, a typo or a name squatted on an earlier registry in the list can resolve to something you did not intend. Prefer aliases, which give the same convenience with an explicit, reviewable mapping.

Do aliases override unqualified-search-registries? Yes. Podman checks the alias table first, and only falls back to iterating the search registries if no alias matches. That makes a drop-in alias file the cleanest way to keep short names working under enforcing mode.

Does docker.io/nginx count as fully qualified? It works, but the canonical form for Docker Hub official images is docker.io/library/nginx. Podman normalizes the shorter form, though writing library/ explicitly avoids surprises when the same manifest is mirrored elsewhere. For more container troubleshooting, see the Podman guides.