{"record":{"id":"c12e67489a05c2e5","repo":"docker/cli","slug":"failed-to-configure-transport-w","errorCode":null,"errorMessage":"failed to configure transport: %w","messagePattern":"failed to configure transport: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/registryclient/client.go","lineNumber":156,"sourceCode":"\t\t\thttpTransport, err = c.getHTTPTransportForRepoEndpoint(ctx, repoEndpoint)\n\t\t\tif err != nil {\n\t\t\t\treturn nil, err\n\t\t\t}\n\t\t}\n\t}\n\treturn distributionclient.NewRepository(repoName, repoEndpoint.BaseURL(), httpTransport)\n}\n\nfunc (c *client) getHTTPTransportForRepoEndpoint(ctx context.Context, repoEndpoint repositoryEndpoint) (http.RoundTripper, error) {\n\thttpTransport, err := getHTTPTransport(\n\t\tc.authConfigResolver(ctx, repoEndpoint.indexInfo.Name),\n\t\trepoEndpoint.endpoint,\n\t\trepoEndpoint.repoName,\n\t\tc.userAgent,\n\t\trepoEndpoint.actions,\n\t)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to configure transport: %w\", err)\n\t}\n\treturn httpTransport, nil\n}\n\n// GetManifest returns an ImageManifest for the reference\nfunc (c *client) GetManifest(ctx context.Context, ref reference.Named) (manifesttypes.ImageManifest, error) {\n\tvar result manifesttypes.ImageManifest\n\tfetch := func(ctx context.Context, repo distribution.Repository, ref reference.Named) (bool, error) {\n\t\tvar err error\n\t\tresult, err = fetchManifest(ctx, repo, ref)\n\t\treturn result.Ref != nil, err\n\t}\n\n\terr := c.iterateEndpoints(ctx, ref, fetch)\n\treturn result, err\n}\n\n// GetManifestList returns a list of ImageManifest for the reference","sourceCodeStart":138,"sourceCodeEnd":174,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/internal/registryclient/client.go#L138-L174","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Unwrap the error (errors.Unwrap / errors.As) to reach the concrete cause — usually the \"error pinging v2 registry\" from 603.","Reach the registry's /v2/ endpoint manually (curl -v https://<host>/v2/) to confirm connectivity and TLS.","For a self-signed or private-CA registry, pass insecure=true (NewRegistryClient) or configure the host as an insecure registry.","Check HTTP_PROXY / HTTPS_PROXY / NO_PROXY env vars and Docker daemon proxy settings.","Re-run `docker login <host>` to refresh credentials feeding the authConfigResolver."],"exampleFix":"// before\ncli := registryclient.NewRegistryClient(resolver, ua, false)\n\n// after (registry uses a self-signed cert)\ncli := registryclient.NewRegistryClient(resolver, ua, true) // insecure=true","handlingStrategy":"retry","validationCode":"// Preflight: confirm the registry's /v2/ endpoint is reachable before\n// constructing the client transport.\nfunc pingV2(ctx context.Context, regURL string, insecure bool) error {\n    client := &http.Client{Timeout: 10 * time.Second}\n    if insecure {\n        client.Transport = &http.Transport{TLSClientConfig: &tls.Config{InsecureSkipVerify: true}}\n    }\n    req, _ := http.NewRequestWithContext(ctx, \"GET\", strings.TrimRight(regURL, \"/\")+\"/v2/\", nil)\n    resp, err := client.Do(req)\n    if err != nil {\n        return err\n    }\n    defer resp.Body.Close()\n    if resp.StatusCode/100 != 2 {\n        return fmt.Errorf(\"v2 ping returned %s\", resp.Status)\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":"// Inspect the wrapped chain to decide retry vs. hard fail.\nvar pingErr somePingError\nif errors.As(err, &pingErr) {\n    if isTransient(err) { /* retry with backoff */ } else { /* surface to user */ }\n}","preventionTips":["Run a /v2/ preflight ping before heavy operations.","Configure TLS correctly or explicitly enable insecure mode for private CAs.","Keep HTTP_PROXY/HTTPS_PROXY consistent between the daemon and the client.","Refresh credentials with docker login before long-running jobs."],"tags":["docker","registry","network","tls","authentication"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}