Fix Podman Short-Name Resolution Errors

podman pull alpine looks simple, but Podman must decide which registry hosts that name before it downloads anything. When resolution policy blocks an ambiguous short name — especially in CI, cron, or systemd without a terminal — the pull fails before the registry is contacted. This guide maps the error text you see to the fix that actually sticks.

short-name resolution enforced but cannot prompt without a TTY

On RHEL 10.2, short-name-mode is enforcing. Pull an image that has no alias and cannot be resolved without a choice, with stdin not attached to a terminal:

podman pull bogus-unqualified-lab-image:999 </dev/null

Sample output:

Error: short-name resolution enforced but cannot prompt without a TTY

The same message appears when a script pipes input or runs under automation that is not a real TTY. Podman would ask which registry to trust in an interactive shell; without a prompt channel it refuses to guess.

On stock RHEL, common names such as alpine often succeed at the resolution step because distribution drop-ins ship aliases — a later rate-limit or auth error is a different problem. To reproduce the TTY error on a enforcing host, use a name that has no alias in your effective configuration.

Why the error happens

Short-name resolution walks a fixed decision tree:

alpine
  ↓
existing short-name alias?
  ├─ yes → use alias target
  └─ no
       ↓
unqualified-search-registries defined?
       ↓
short-name-mode
       ↓
enforcing + ambiguous + no TTY → error (cannot prompt)
permissive/disabled → search registries (policy-dependent)

Under enforcing, Podman treats an unqualified name without a definitive alias as a security decision. Namespace squatting on an early search registry is a real risk — Podman will not silently probe multiple public registries in non-interactive mode. That is why CI jobs hit this error more often than an interactive laptop session where you can answer a prompt.

short-name … did not resolve to an alias

A second failure mode appears when there is no alias and no search registry list Podman can use. On RHEL 10.2 with search registries configured, an unknown short name usually hits the TTY error first. To see the no-search message, point Podman at a minimal config with enforcing mode only:

short-name-mode = "enforcing"

Save that as /tmp/registries-no-search.conf, then pull a throwaway name without a TTY:

CONTAINERS_REGISTRIES_CONF=/tmp/registries-no-search.conf podman pull bogus-unqualified-lab-image:999 </dev/null

Sample output:

Error: short-name "bogus-unqualified-lab-image:999" did not resolve to an alias and no unqualified-search registries are defined in "/tmp/registries-no-search.conf"

Older Podman releases sometimes prefixed that text with error getting default registries to try: — the core meaning is unchanged. The path at the end of the message is whichever registries.conf file governed that pull.

If your distribution ships alias drop-ins (RHEL includes 000-shortnames.conf), a name like alpine may never reach this error because an alias matches first. Test with a name you know is not aliased on your host.

Check current short-name configuration

Read what the running host actually enforces before you change policy:

grep -R -E 'short-name-mode|unqualified-search-registries|\[aliases\]' /etc/containers/registries.conf /etc/containers/registries.conf.d/ 2>/dev/null

Sample output on RHEL 10.2:

/etc/containers/registries.conf:unqualified-search-registries = ["registry.access.redhat.com", "registry.redhat.io", "docker.io"]
/etc/containers/registries.conf:short-name-mode = "enforcing"
/etc/containers/registries.conf.d/000-shortnames.conf:[aliases]
/etc/containers/registries.conf.d/001-rhel-shortnames.conf:[aliases]

List drop-in files so you know which alias tables merge in:

find /etc/containers/registries.conf.d -maxdepth 1 -type f -print

Rootless users can also maintain $HOME/.config/containers/registries.conf — when that main file exists it replaces the system main file for that user. Do not assume upstream defaults: RHEL ships enforcing explicitly even though containers/image defaults to permissive when the setting is absent.

Best fix for scripts: use a fully qualified image name

Replace ambiguous short names with the registry, repository, and tag you intend:

podman pull docker.io/library/alpine:latest

For Red Hat content, prefer distribution registries:

registry.access.redhat.com/ubi9/ubi-minimal:latest
registry.redhat.io/...

A fully qualified reference skips the short-name prompt path entirely. Podman contacts that registry directly — no alias table lookup and no search-registry guessing.

This is the primary recommendation for automation that runs without a TTY:

• shell scripts and CI pipelines
• cron jobs and systemd units
• Quadlet .container files
• podman kube play manifests

Pull images with podman pull uses fully qualified names for the same reason.

Add a short-name alias

When operators want a short name on controlled hosts, map it in [aliases]:

[aliases]
"demo" = "quay.io/podman/hello"

Place the stanza in a drop-in such as /etc/containers/registries.conf.d/10-team-aliases.conf rather than editing the distribution file in place. Pull with the short name:

podman pull demo:latest

Sample output:

Trying to pull quay.io/podman/hello:latest...
Getting image source signatures
Copying blob sha256:81df7ff16254...
Copying config sha256:5dd467fce50b...
Writing manifest to image destination
5dd467fce50b56951185da365b5feee75409968cbab5767b9b59e325fb2ecbc0

Alias targets must be fully qualified repositories — no tag in the alias value; Podman appends :latest or the tag from your command. Aliases suit admin-managed fleets where you document the mapping; they are not a substitute for qualified names in portable automation.

RHEL already maps many common names. Inspect the shipped table:

grep '"alpine"' /etc/containers/registries.conf.d/000-shortnames.conf

Sample output:

"alpine" = "docker.io/library/alpine"

Machine-generated aliases can override your manual alias

When short-name-mode allows interactive resolution, Podman can cache your choice in:

A machine-generated entry for a short name takes precedence over the same name in registries.conf. Typical failure pattern:

1. An admin adds or updates [aliases] in a drop-in.
2. An older cached mapping still points at a different repository.
3. Pulls keep using the cache until you remove the stale entry.

Check whether a cache file exists:

ls -la /var/cache/containers/short-name-aliases.conf 2>/dev/null || echo 'no machine-generated alias cache'

On a fresh RHEL 10.2 lab host only the lock file was present — no cache yet. After interactive pulls under permissive, entries can appear and surprise later changes.

CONTAINERS_REGISTRIES_CONF is useful for isolated tests because it selects a specific registries.conf. On current containers/image, setting it also prevents the normal registries.conf.d drop-ins from being loaded. This makes it useful for reproducing resolution behavior without distribution-provided aliases. For precedence debugging on the normal merged config, inspect the full tree with Podman registries.conf explained.

Configure unqualified-search-registries

When no alias matches, Podman can search registries in list order:

unqualified-search-registries = [
  "registry.access.redhat.com",
  "registry.redhat.io",
  "docker.io"
]

Order matters — the first registry that serves a matching repository wins. Expanding the list to silence errors increases namespace-squatting risk:

• an unexpected image on an early registry can replace the one you meant to run
• more public registries in the list means more candidates Podman may probe under permissive modes

Under enforcing, unqualified-search-registries does not help a non-interactive pull when multiple candidate registries require a choice. If only one candidate applies, Podman can proceed without prompting. The list also supplies candidates for interactive selection and for permissive / disabled behavior. Do not expand the list blindly; prefer aliases or fully qualified names.

short-name-mode

Changing short-name-mode is a policy decision, not the first fix for automation. Fully qualified image names are deterministic regardless of mode.

On this lab host, permissive with a search list attempted docker.io and quay.io for an unknown short name instead of the TTY error — still failing at the registry, but for pull-denied reasons rather than short-name enforcement.

CI and Quadlet

Avoid bare short names in units that run headless.

Bad Quadlet fragment:

Image=alpine

Recommended:

Image=docker.io/library/alpine:latest

Apply the same rule everywhere resolution policy may differ between hosts:

• shell scripts
• GitHub Actions and GitLab CI
• podman kube play YAML
• systemd ExecStart= lines

Qualified names behave the same in every environment.

Debug short-name resolution

Raise log verbosity to see alias hits and registry attempts:

podman --log-level=debug pull demo:latest 2>&1 | grep -iE 'Resolved|alias|Trying to pull|unqualified'

Sample output (custom alias to quay.io):

Trying to pull quay.io/podman/hello:latest...

For a shipped alias on RHEL:

podman --log-level=debug pull alpine </dev/null 2>&1 | grep -iE 'Resolved|alias|Trying to pull'

Sample output:

Resolved "alpine" as an alias (/etc/containers/registries.conf.d/000-shortnames.conf)
Trying to pull docker.io/library/alpine:latest...

Trim debug with grep — full debug logs are noisy. The Resolved ... as an alias line tells you which file won; Trying to pull shows the expanded reference Podman actually contacts.

Troubleshooting

References

• containers-registries.conf(5)
• Podman pull manual
• Podman rootless tutorial — registries

Summary

Podman short-name errors mean the CLI refused to guess which registry owns an unqualified image name. Under enforcing — the RHEL 10.2 default — non-interactive pulls fail with cannot prompt without a TTY when no alias defines the name. When no alias exists and no search registries are configured, you get did not resolve to an alias instead.

The durable fix for scripts, CI, and Quadlet is a fully qualified image reference such as docker.io/library/alpine:latest or registry.access.redhat.com/ubi9/ubi-minimal:latest. Aliases in registries.conf drop-ins help on managed hosts where short names are intentional. Watch the machine-generated short-name-aliases.conf cache — it overrides manual aliases for the same key.

Changing short-name-mode or expanding unqualified-search-registries can silence errors but trades predictability for convenience. Inspect your effective configuration with grep and podman --log-level=debug before editing policy. For mirrors, blocked registries, and full file layout, continue with Podman registries.conf explained.