docker/cli · error

failed to configure transport

Error message

failed to configure transport: %w

What it means

Wraps any error returned by getHTTPTransport while building the authenticated round-tripper for a registry endpoint. The most common underlying cause is the v2 ping failure (error 603), but it can also wrap TLS dial errors, proxy errors, or auth-challenge construction failures. Because it is an outer wrapper, the real reason is in errors.Unwrap(err).

Solutions

1. Unwrap the error (errors.Unwrap / errors.As) to reach the concrete cause — usually the "error pinging v2 registry" from 603.
2. Reach the registry's /v2/ endpoint manually (curl -v https://<host>/v2/) to confirm connectivity and TLS.
3. For a self-signed or private-CA registry, pass insecure=true (NewRegistryClient) or configure the host as an insecure registry.
4. Check HTTP_PROXY / HTTPS_PROXY / NO_PROXY env vars and Docker daemon proxy settings.
5. Re-run `docker login <host>` to refresh credentials feeding the authConfigResolver.

Example fix

// before
cli := registryclient.NewRegistryClient(resolver, ua, false)

// after (registry uses a self-signed cert)
cli := registryclient.NewRegistryClient(resolver, ua, true) // insecure=true

// Preflight: confirm the registry's /v2/ endpoint is reachable before
// constructing the client transport.
func pingV2(ctx context.Context, regURL string, insecure bool) error {
    client := &http.Client{Timeout: 10 * time.Second}
    if insecure {
        client.Transport = &http.Transport{TLSClientConfig: &tls.Config{InsecureSkipVerify: true}}
    }
    req, _ := http.NewRequestWithContext(ctx, "GET", strings.TrimRight(regURL, "/")+"/v2/", nil)
    resp, err := client.Do(req)
    if err != nil {
        return err
    }
    defer resp.Body.Close()
    if resp.StatusCode/100 != 2 {
        return fmt.Errorf("v2 ping returned %s", resp.Status)
    }
    return nil
}

// Inspect the wrapped chain to decide retry vs. hard fail.
var pingErr somePingError
if errors.As(err, &pingErr) {
    if isTransient(err) { /* retry with backoff */ } else { /* surface to user */ }
}

When it happens

Trigger: getRepositoryForReference -> getHTTPTransportForRepoEndpoint -> getHTTPTransport fails: registry unreachable, TLS handshake failure, self-signed cert without insecure mode, HTTP_PROXY/HTTPS_PROXY misconfigured, or the registry not speaking the v2 API during the ping.

Common situations: Self-signed registry without --insecure; corporate MITM proxy intercepting TLS; DNS or firewall blocking the registry host; registry behind a reverse proxy that strips /v2/; expired credentials causing the ping's auth flow to break.

Related errors

• error pinging v2 registry
• error establishing connection to trust repository
• no signatures or cannot access
• no signers for
• unable to get system cert pool

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

Appendix: source

Thrown at internal/registryclient/client.go:156

			httpTransport, err = c.getHTTPTransportForRepoEndpoint(ctx, repoEndpoint)
			if err != nil {
				return nil, err
			}
		}
	}
	return distributionclient.NewRepository(repoName, repoEndpoint.BaseURL(), httpTransport)
}

func (c *client) getHTTPTransportForRepoEndpoint(ctx context.Context, repoEndpoint repositoryEndpoint) (http.RoundTripper, error) {
	httpTransport, err := getHTTPTransport(
		c.authConfigResolver(ctx, repoEndpoint.indexInfo.Name),
		repoEndpoint.endpoint,
		repoEndpoint.repoName,
		c.userAgent,
		repoEndpoint.actions,
	)
	if err != nil {
		return nil, fmt.Errorf("failed to configure transport: %w", err)
	}
	return httpTransport, nil
}

// GetManifest returns an ImageManifest for the reference
func (c *client) GetManifest(ctx context.Context, ref reference.Named) (manifesttypes.ImageManifest, error) {
	var result manifesttypes.ImageManifest
	fetch := func(ctx context.Context, repo distribution.Repository, ref reference.Named) (bool, error) {
		var err error
		result, err = fetchManifest(ctx, repo, ref)
		return result.Ref != nil, err
	}

	err := c.iterateEndpoints(ctx, ref, fetch)
	return result, err
}

// GetManifestList returns a list of ImageManifest for the reference

View on GitHub (pinned to 4f84911bfe)