docker/cli · error

failed to parse repo name from

Error message

failed to parse repo name from %s: %w

What it means

Thrown in getRepositoryForReference when reference.WithName(repoEndpoint.repoName) rejects the repository path extracted from your image reference. The repoName comes from reference.Path(reference.TrimNamed(ref)), so this means the path segment of the reference contains characters the Docker reference grammar forbids (uppercase letters, underscores in the wrong place, disallowed punctuation, over-long components). It indicates a malformed image name, not a network problem.

Solutions

1. Inspect the %s value in the message to find which component has illegal characters and lowercase / sanitize it.
2. Validate the reference with reference.ParseNamed (or reference.WithName on the path) before calling any RegistryClient method.
3. Build references via reference.WithName / reference.ParseNamed rather than string concatenation so the grammar is enforced early.
4. Ensure each path component matches [a-z0-9]+(?:[._-][a-z0-9]+)* and is within length limits.

Example fix

// before
ref, _ := reference.ParseNamed("MyApp/Image:1.0")
c.GetManifest(ctx, ref) // -> failed to parse repo name

// after
ref, _ := reference.ParseNamed("myapp/image:1.0")
c.GetManifest(ctx, ref)

// Validate the reference before calling any RegistryClient method.
func validRepoRef(s string) (reference.Named, error) {
    ref, err := reference.ParseNamed(s)
    if err != nil {
        return nil, fmt.Errorf("invalid image reference %q: %w", s, err)
    }
    // re-validate the path component the same way the client will
    if _, err := reference.WithName(reference.Path(reference.TrimNamed(ref))); err != nil {
        return nil, fmt.Errorf("invalid repository name in %q: %w", s, err)
    }
    return ref, nil
}

// Confirm a reference carries a parseable repository path.
func hasValidRepoName(ref reference.Named) bool {
    _, err := reference.WithName(reference.Path(reference.TrimNamed(ref)))
    return err == nil
}

When it happens

Trigger: Calling GetManifest / GetManifestList / MountBlob / PutManifest with a reference whose path is not a legal repository name — e.g. an uppercase component like "MyApp/img", a name containing illegal symbols, or a programmatically constructed ref that interpolates a slash-heavy or symbolic path.

Common situations: Typo'd image name with capitals; CI script building a ref from an env var containing uppercase branch names; custom registry namespace using characters the reference parser rejects; ref built by string concatenation instead of the reference package helpers.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• no tag or digest
• image manifest for does not exist
• invalid image reference for service
• tag can't be used with --all-tags/-a
• tag can't be used with --all-tags/-a

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/cba3272b5b4b6b98. Report an issue: GitHub.

Appendix: source

Thrown at internal/registryclient/client.go:125

		return "", err
	}

	_, opts, err := getManifestOptionsFromReference(ref)
	if err != nil {
		return "", err
	}

	dgst, err := manifestService.Put(ctx, manifest, opts...)
	if err != nil {
		return dgst, fmt.Errorf("failed to put manifest %s: %w", ref, err)
	}
	return dgst, nil
}

func (c *client) getRepositoryForReference(ctx context.Context, ref reference.Named, repoEndpoint repositoryEndpoint) (distribution.Repository, error) {
	repoName, err := reference.WithName(repoEndpoint.repoName)
	if err != nil {
		return nil, fmt.Errorf("failed to parse repo name from %s: %w", ref, err)
	}
	httpTransport, err := c.getHTTPTransportForRepoEndpoint(ctx, repoEndpoint)
	if err != nil {
		if !strings.Contains(err.Error(), "server gave HTTP response to HTTPS client") {
			return nil, err
		}
		if !repoEndpoint.endpoint.TLSConfig.InsecureSkipVerify {
			return nil, httpProtoError{cause: err}
		}
		// --insecure was set; fall back to plain HTTP
		if url := repoEndpoint.endpoint.URL; url != nil && url.Scheme == "https" {
			url.Scheme = "http"
			httpTransport, err = c.getHTTPTransportForRepoEndpoint(ctx, repoEndpoint)
			if err != nil {
				return nil, err
			}
		}
	}

View on GitHub (pinned to 4f84911bfe)