Skip to content

feature: Add proper error reporting for inspect #2589

Closed as not planned
Closed as not planned

Description

@gabyx

It would be very nice if skopeo would have proper error reporting interface. Especially on

skopeo inspect "docker:/..."

where its not clear where the image does not exist or there was an authentication error.

Its not clear how to deal with errors with skopeo in general and for tooling this is a problem.

I see the following errors on all skopeo commands:

  • exit code X: Authorization Error

on inspect:

  • exit code Y: -> manifest unknow or image not existing (currently its somehow exit 2 but its nowhere documented?)

Activity

  1. mtrmac commented on Apr 30, 2025

    @mtrmac
    Contributor

    Thanks for reaching out. Please be more specific in what you mean by “proper”.

    Are you talking about exit codes only? And, if relevant, what conditions?

    (Ultimately, there’s very little that can fit into an 8-bit field. At some point, it would be easier to write a Go program a receive full Go types directly … to the extent those make any promises about reported error types, which is also somewhat limited.)

    The current exit status 2 is documented in skopeo(1). But note the caveat there; there is no way to reliably distinguish an authentication failure from a missing image, in general. Some things just aren’t possible.

  2. gabyx commented on May 3, 2025

    @gabyx
    Author

    Ah ok, jeah I mean only exit code: so you say the container registry API does not have a destinction in http response status codes between notfound and auth error? Strange?
    especially for the transport docker://

  3. mtrmac commented on May 5, 2025

    @mtrmac
    Contributor

    It does have that distinction, but there have been registries which replied with “not found” to requests to read something the user (anonymous or authenticated) does not have the right to to access — I guess with the idea that even disclosing the existence of that name is disclosing private information.

  4. gabyx commented on May 5, 2025

    @gabyx
    Author

    Ah, ok. Its just hard to know what maps to 2? Possibly anything? Also server error? Or only failures of Unauthorized/Notfound etc for that Inspect operations?

    It just leads to code like this, but maybe there is no better way?

    func checkIfExists(skopeo *skopeo.Context, dest string) (exists bool, err error) {
    	log.Info("Checking if image already exists.")
    
    	cmd := []string{"inspect"}
    	cmd = append(cmd, dest)
    	exists = true
    
    	// When repository does not exist yet ->
    	// we get exit code 1, an we need to handle it somehow.
    
    	// The workaround below is really ugly and prone to break!
    	resp, e := skopeo.GetCombinedWithEC(
    		func(cmdError *exec.CmdError) error {
    			if cmdError != nil && cmdError.ExitCode() == 2 {
    				exists = false
    
    				return nil
    			}
    
    			return cmdError
    		},
    		cmd...)
    
    	if e != nil {
    		if strings.Contains(resp, "invalid status code from registry 403") ||
    			strings.Contains(resp, "requested access to the resource is denied") {
    			// we have 403 which is ok, the registry does not yet exist.
    			exists = false
    		}
    
    		return true, errors.AddContext(
    			e,
    			"could not check if image '%s' exists:\nstdout/err:\n%s",
    			dest,
    			resp,
    		)
    	}
    
    	return exists, nil
    }
  5. mtrmac commented on May 5, 2025

    @mtrmac
    Contributor

    I’d expect the behavior to be stable for a given server (and server’s software version?). But writing a tool reliably working for any registry on the internet is difficult.

    (To be explicit, nothing in Skopeo promises to continue to use the exact text invalid status code from registry 403 in error messages, and we did change error texts in the past.)

  6. gabyx commented on May 5, 2025

    @gabyx
    Author

    @mtrmac : Jeah thats correct, its a dumb workaround =). I now understand that its kind of difficult to make it work in all cases. The tool is great though!

  7. mtrmac commented on May 28, 2025

    @mtrmac
    Contributor

    As an example of the difficulty of doing something useful here, recently I have noticed:

    % skopeo inspect docker://quay.io/libpod/alpine:nonexistenttag
    FATA[0001] Error parsing image name "docker://quay.io/libpod/alpine:nonexistenttag": reading manifest nonexistenttag in quay.io/libpod/alpine: manifest unknown 
    % skopeo inspect docker://quay.io/libpod/nonexistentrepo                     
    FATA[0001] Error parsing image name "docker://quay.io/libpod/nonexistentrepo": reading manifest latest in quay.io/libpod/nonexistentrepo: unauthorized: access to the requested resource is not authorized 
  8. github-actions commented on Jun 28, 2025

    @github-actions

    A friendly reminder that this issue had no activity for 30 days.

  9. mtrmac commented on Mar 24, 2026

    @mtrmac
    Contributor

    Revisiting this a bit — I don’t think there’s much that makes sense to try to fit into the exit status. We certainly can’t fit all possible HTTP statuses there :)

    For the provided example, which is trying to check whether an image “exists”, that’s already supposed to be exit status 2 — but with all the limitations and issues noted above. (I don’t think it’s at reasonable in general to treat HTTP 403 as “image does not exist”).

    If we manage to improve the “image does not exist” heuristics, that would continue to use exit status 2.

    But, noting that the caller is Go: use go.podman.io/image/v5 directly, and that gets quite a bit more granularity. By no means full granularity, quite a few of the error types are private, but there’s much more that can be done at that level.

  10. locked as resolved and limited conversation to collaborators on Jul 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions