Distinguish image-not-found from authentication errors (#216)

Co-authored-by: Claude <noreply@anthropic.com>

Author: jadolg

index.html

@@ -368,14 +368,17 @@
                     detail: null,
                 };
 
-                // Check for common error patterns
-                if (
+                // Check for common error patterns — check backend status-based
+                // messages first, then fall back to registry error codes.
+                if (errorMessage.includes("image not found")) {
+                    result.title = "Image Not Found";
+                    result.message = "The requested image does not exist.";
+                } else if (
                     errorMessage.includes("MANIFEST_UNKNOWN") ||
                     errorMessage.includes("manifest unknown")
                 ) {
                     result.title = "Image Not Found";
                     result.message = "The requested image tag does not exist.";
-                    // Try to extract the tag
                     const tagMatch = errorMessage.match(
                         /unknown tag=([^\s}"]+)/,
                     );
@@ -388,6 +391,10 @@
                 ) {
                     result.title = "Repository Not Found";
                     result.message = "The requested repository does not exist.";
+                } else if (errorMessage.includes("access denied")) {
+                    result.title = "Access Denied";
+                    result.message =
+                        "The image may not exist, or you may need credentials to access it.";
                 } else if (
                     errorMessage.includes("UNAUTHORIZED") ||
                     errorMessage.includes("unauthorized")

registry.go

@@ -19,6 +19,15 @@ const bearerPrefix = "Bearer "
 const responseBodyStr = "response body"
 const invalidImageReferenceFormat = "invalid image reference: %w"
 
+// ErrImageNotFound is returned when the registry responds with 404 for a manifest request.
+type ErrImageNotFound struct {
+	Image string
+}
+
+func (e *ErrImageNotFound) Error() string {
+	return fmt.Sprintf("image not found: %s", e.Image)
+}
+
 // ImageReference represents a parsed Docker image reference
 type ImageReference struct {
 	Registry   string
@@ -228,7 +237,7 @@ func (c *RegistryClient) fetchToken(realm, service, scope string, creds Registry
 	if resp.StatusCode != http.StatusOK {
 		body, _ := io.ReadAll(io.LimitReader(resp.Body, 4096))
 		log.WithField("response_body", string(body)).WithField("status_code", resp.StatusCode).Debug("Authentication request failed")
-		return "", fmt.Errorf("authentication failed with status %d", resp.StatusCode)
+		return "", fmt.Errorf("authentication failed (status %d): check credentials or verify the image exists", resp.StatusCode)
 	}
 
 	var tokenResp struct {
@@ -328,7 +337,14 @@ func (c *RegistryClient) GetPlatforms(ref ImageReference) ([]Platform, error) {
 	}
 	defer closeWithLog(resp.Body, responseBodyStr)
 
-	if resp.StatusCode != http.StatusOK {
+	switch resp.StatusCode {
+	case http.StatusOK:
+		// handled below
+	case http.StatusNotFound:
+		return nil, &ErrImageNotFound{Image: ref.Repository + ":" + ref.Tag}
+	case http.StatusUnauthorized, http.StatusForbidden:
+		return nil, fmt.Errorf("access denied (status %d): check credentials or verify the image exists", resp.StatusCode)
+	default:
 		body, _ := io.ReadAll(resp.Body)
 		return nil, fmt.Errorf("failed to get manifest: %d - %s", resp.StatusCode, string(body))
 	}
@@ -414,7 +430,14 @@ func (c *RegistryClient) getManifest(ref ImageReference, platform Platform) (*Ma
 	}
 	defer closeWithLog(resp.Body, responseBodyStr)
 
-	if resp.StatusCode != http.StatusOK {
+	switch resp.StatusCode {
+	case http.StatusOK:
+		// handled below
+	case http.StatusNotFound:
+		return nil, &ErrImageNotFound{Image: ref.Repository + ":" + ref.Tag}
+	case http.StatusUnauthorized, http.StatusForbidden:
+		return nil, fmt.Errorf("access denied (status %d): check credentials or verify the image exists", resp.StatusCode)
+	default:
 		body, _ := io.ReadAll(io.LimitReader(resp.Body, 4096))
 		return nil, fmt.Errorf("failed to get manifest: %d - %s", resp.StatusCode, string(body))
 	}

server.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"embed"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"net"
 	"net/http"
@@ -72,7 +73,7 @@ func (s *Server) Start(ctx context.Context) (*http.Server, error) {
 		"cache_dir": s.cache.Dir(),
 	}).Info("Starting server")
 	go func() {
-		if err := srv.Serve(ln); err != nil && err != http.ErrServerClosed {
+		if err := srv.Serve(ln); err != nil && !errors.Is(err, http.ErrServerClosed) {
 			log.WithError(err).Fatal("Server error")
 		}
 	}()
@@ -153,7 +154,11 @@ func (s *Server) imageHandler(w http.ResponseWriter, r *http.Request) {
 			"image": imageName,
 		}).WithError(err).Error("Failed to download image")
 		errorsTotalMetric.Inc()
-		writeJSONError(w, "failed to download image", http.StatusInternalServerError)
+		if notFound, match := errors.AsType[*ErrImageNotFound](err); match {
+			writeJSONError(w, notFound.Error(), http.StatusNotFound)
+		} else {
+			writeJSONError(w, fmt.Sprintf("failed to download image: %v", err), http.StatusInternalServerError)
+		}
 		return
 	}
 	imagePath := result.(string)
@@ -171,7 +176,11 @@ func (s *Server) platformsHandler(w http.ResponseWriter, r *http.Request) {
 	platforms, err := GetImagePlatforms(imageName)
 	if err != nil {
 		log.WithField("image", imageName).WithError(err).Error("Failed to get platforms")
-		writeJSONError(w, "failed to get platforms", http.StatusInternalServerError)
+		if notFound, match := errors.AsType[*ErrImageNotFound](err); match {
+			writeJSONError(w, notFound.Error(), http.StatusNotFound)
+		} else {
+			writeJSONError(w, fmt.Sprintf("failed to get platforms: %v", err), http.StatusInternalServerError)
+		}
 		return
 	}
 	if platforms == nil {