amir20/dozzle · error

invalid image reference

Error message

invalid image reference %q: empty repository

What it means

After stripping the digest and tag, the remaining string is the repository. If it is empty (reference was just a registry, a tag, or ':'), ParseReference returns this error since a repository name is the minimum requirement for an image reference.

Solutions

1. Include a repository path: registry host plus image name, e.g. localhost:5000/myapp:1.0
2. Do not pass a bare registry address where an image reference is expected
3. Split your config into registry + image fields and join them before parsing

Example fix

// before
check("localhost:5000") // treated as registry-only
// after
check("localhost:5000/myapp:1.0")

parts := strings.SplitN(strings.TrimSuffix(strings.TrimSuffix(ref, "@"+digest), ":"+tag), "/", 2)
if len(parts) < 2 && !strings.Contains(ref, ".") && !strings.Contains(ref, "localhost") {
    // ensure a repository path exists
}

func hasRepository(ref string) bool {
    base := ref
    if i := strings.Index(base, "@"); i != -1 { base = base[:i] }
    if i := strings.LastIndex(base, ":"); i != -1 { base = base[:i] }
    return base != "" && !strings.ContainsAny(base, ":")
}

if _, err := imagecheck.ParseReference(ref); err != nil {
    if strings.Contains(err.Error(), "empty repository") {
        return fmt.Errorf("got registry-only value %q; provide image name", ref)
    }
    return err
}

When it happens

Trigger: Passing references like ":1.25", "localhost:5000", "localhost:5000:latest", or ":" where no repository path component exists after registry/tag extraction.

Common situations: Confusing registry endpoint with a full image name (passing only the registry host), parsing an image spec where the repo part was mistakenly consumed, or severely malformed config values.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• empty image reference
• invalid image reference
• invalid image reference
• Failed to save alert
• Toast id is required when once is true

AI-assisted analysis of amir20/dozzle@d9463cbe21 (2026-09-07). Data as JSON: /api/errors/bbc049ab9809ef0f. Report an issue: GitHub.

Appendix: source

Thrown at internal/imagecheck/reference.go:136

	// reference written as index.docker.io/library/nginx never lines up with
	// the "nginx@sha256:..." that Docker records locally.
	if _, aliased := dockerHubAliases[registry]; aliased {
		registry = defaultRegistry
	}

	tag := ""
	// Only treat a colon as a tag separator when it is not part of a registry
	// port, which has already been stripped above.
	if i := strings.LastIndex(remainder, ":"); i != -1 {
		tag = remainder[i+1:]
		remainder = remainder[:i]
		if tag == "" {
			return Reference{}, fmt.Errorf("invalid image reference %q: empty tag", ref)
		}
	}

	if remainder == "" {
		return Reference{}, fmt.Errorf("invalid image reference %q: empty repository", ref)
	}

	// Official images live under library/ but are referenced without it.
	if registry == defaultRegistry && !strings.Contains(remainder, "/") {
		remainder = "library/" + remainder
	}

	if tag == "" && digest == "" {
		tag = defaultTag
	}

	return Reference{
		Registry:   registry,
		Repository: remainder,
		Tag:        tag,
		Digest:     digest,
	}, nil
}

View on GitHub (pinned to d9463cbe21)