docker/cli · error

error: error contacting notary server

Error message

error: error contacting notary server: %v

What it means

Returned by NotaryError (trust.go:242) when the notary error is storage.NetworkError — the client could not reach or successfully communicate with the Notary server over the network. This is distinct from missing data: the request itself failed (DNS, connection refused, TLS, timeout, HTTP transport error).

Solutions

1. Verify connectivity: `curl -v https://<trust-server>/v2/` and check DNS/firewall/proxy.
2. Set HTTPS_PROXY/HTTP_PROXY if a corporate proxy is required.
3. Confirm DOCKER_CONTENT_TRUST_SERVER is correct and reachable; fall back to notary.docker.io by unsetting it.
4. Retry after confirming the server cert chain validates against the configured CA bundle.

Example fix

# before: blocked by proxy, fails with NetworkError
DOCKER_CONTENT_TRUST=1 docker push example.com/app

# after: route through the corporate proxy
export HTTPS_PROXY=http://proxy.corp:3128
DOCKER_CONTENT_TRUST=1 docker push example.com/app

// Pre-flight connectivity to the trust server
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
if _, err := http.NewRequestWithContext(ctx, http.MethodGet, trustServer+"/v2/", nil); err != nil {
    return fmt.Errorf("trust server URL invalid: %w", err)
}

// Retry transient network errors with backoff
var last error
for i := 0; i < 3; i++ {
    last = trustedOp(repo)
    if last == nil || !errors.As(last, &storage.NetworkError{}) { break }
    time.Sleep(time.Duration(1<<i) * time.Second)
}

When it happens

Trigger: Any trusted operation when the network path to the Notary server (DOCKER_CONTENT_TRUST_SERVER or notary.docker.io) fails: DNS resolution error, connection refused, TLS handshake failure, or a timeout. notary's storage layer wraps the HTTP error as NetworkError and NotaryError maps it here.

Common situations: Offline or behind a restrictive corporate proxy/firewall blocking the Notary port, a typo'd or unreachable trust server hostname, expired/invalid TLS certs on the server, or transient outages of notary.docker.io.

Related errors

• error: no trust data available for remote repository
• error retrieving signers for
• no valid signing keys for delegation roles
• cannot push a digest reference
• no targets found, provide a specific tag in order to sign it

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

Appendix: source

Thrown at cmd/docker-trust/internal/trust/trust.go:242

		if v := env["default"]; v != "" && alias != data.CanonicalRootRole.String() {
			return v, numAttempts > 1, nil
		}
		return baseRetriever(keyName, alias, createNew, numAttempts)
	}
}

// NotaryError formats an error message received from the notary service
func NotaryError(repoName string, err error) error {
	switch err.(type) {
	case *json.SyntaxError:
		logrus.Debugf("Notary syntax error: %s", err)
		return fmt.Errorf("error: no trust data available for remote repository %s. Try running notary server and setting DOCKER_CONTENT_TRUST_SERVER to its HTTPS address", repoName)
	case signed.ErrExpired:
		return fmt.Errorf("error: remote repository %s out-of-date: %v", repoName, err)
	case trustmanager.ErrKeyNotFound:
		return fmt.Errorf("error: signing keys for remote repository %s not found: %v", repoName, err)
	case storage.NetworkError:
		return fmt.Errorf("error: error contacting notary server: %v", err)
	case storage.ErrMetaNotFound:
		return fmt.Errorf("error: trust data missing for remote repository %s or remote repository not found: %v", repoName, err)
	case trustpinning.ErrRootRotationFail, trustpinning.ErrValidationFail, signed.ErrInvalidKeyType:
		return fmt.Errorf("warning: potential malicious behavior - trust data mismatch for remote repository %s: %v", repoName, err)
	case signed.ErrNoKeys:
		return fmt.Errorf("error: could not find signing keys for remote repository %s, or could not decrypt signing key: %v", repoName, err)
	case signed.ErrLowVersion:
		return fmt.Errorf("warning: potential malicious behavior - trust data version is lower than expected for remote repository %s: %v", repoName, err)
	case signed.ErrRoleThreshold:
		return fmt.Errorf("warning: potential malicious behavior - trust data has insufficient signatures for remote repository %s: %v", repoName, err)
	case client.ErrRepositoryNotExist:
		return fmt.Errorf("error: remote trust data does not exist for %s: %v", repoName, err)
	case signed.ErrInsufficientSignatures:
		return fmt.Errorf("error: could not produce valid signature for %s.  If Yubikey was used, was touch input provided?: %v", repoName, err)
	default:
		return err
	}
}

View on GitHub (pinned to 4f84911bfe)