Technology · PRACTICAL GUIDE
Podman says a short image name did not resolve? Prove the registry and alias before editing global search order
Separate a local image from a remote pull, inspect the effective alias and cache, then choose a fully qualified name, scoped alias or approved search list and verify the resulting image identity.
A short-name failure is an identity question before it is a configuration problem. Preserve the literal reference and the failing execution context.
The safe order is local image, effective alias and cache, registry policy, narrow remedy, then source verification.
Capture the literal reference and execution context
Save the exact command and image text before changing configuration. A short name such as `alpine` or `team/app:tag` omits a registry; it may also leave the namespace to policy. Record the Podman version, effective user, rootless or rootful mode, terminal availability and complete error.
Do not translate the name into `docker.io/...` from memory. Distribution defaults differ, and a CI runner or systemd unit cannot answer an interactive ambiguity prompt.
Prove whether the intended image is already local
List local images with their repository, tag, image ID and digest. If a build, load or commit created the image locally, give it an explicit local repository name and use that exact identity. An archive path, container name and image reference are different objects.
Stop here if the task should use the local image. A registry edit cannot repair a wrong local tag, and a remote pull could replace the intended artifact with a different publisher’s image.
Audit the effective configuration and alias cache
Read the user configuration and system configuration that apply to the failing user, including distribution drop-ins. Record `unqualified-search-registries`, `short-name-mode`, the `[aliases]` entry and any cached short-name choice. Rootless and rootful runs can see different files and caches.
Alias keys and values do not include tags or digests. Podman strips a tag or digest for alias lookup and reapplies it to the resolved target. A user configuration can override system policy, so editing only `/etc` may not change the failing run.
Choose the narrowest deterministic remedy
For automation, use a fully qualified registry, namespace and image, preferably with an approved digest when reproducibility matters. For a stable shorthand on managed hosts, add a reviewed alias. Change the global search list only when administrators intentionally authorize every unqualified pull to search those registries in that order.
An interactive prompt can help a human choose once, but it is not a CI contract. Do not switch to permissive or disabled resolution merely to silence an error; document the trust boundary and rollback for any policy change.
Verify the resolved source and close the incident
Repeat the original command through the same user and launcher. Inspect the resulting repository digest, image ID and registry-qualified name, then compare them with the expected publisher or deployment record. Success from another shell or from root does not close a rootless CI failure.
Completion means the original context resolves deterministically to the intended registry-qualified image, the chosen rule is no broader than necessary, and a rollback note identifies the alias or policy entry that changed. If the registry or namespace cannot be verified, stop instead of guessing.
