docker/cli · error

valid https URL required for trust server, got

Error message

valid https URL required for trust server, got %s

What it means

Returned by trust.Server (trust.go:86) when DOCKER_CONTENT_TRUST_SERVER is set to a value that either fails to parse as a URL or whose scheme is not 'https'. Content trust (Notary) mandates TLS for the trust server to prevent tampering with trust metadata. The offending URL is echoed back.

Solutions

1. Set DOCKER_CONTENT_TRUST_SERVER to a full https:// URL, e.g. `https://notary.example.com`.
2. Put TLS (with a valid cert or a custom CA in the cert dir) in front of your Notary server.
3. Double-check for typos, trailing slashes, or missing scheme.
4. Unset the variable to fall back to the default https://notary.docker.io.

Example fix

# before
export DOCKER_CONTENT_TRUST_SERVER=http://notary.local:4443

# after
export DOCKER_CONTENT_TRUST_SERVER=https://notary.local

// Validate the trust server URL scheme before any trusted operation
srv := os.Getenv("DOCKER_CONTENT_TRUST_SERVER")
if srv != "" {
    u, err := url.Parse(srv)
    if err != nil || u.Scheme != "https" {
        return fmt.Errorf("DOCKER_CONTENT_TRUST_SERVER must be https, got %q", srv)
    }
}

When it happens

Trigger: Setting DOCKER_CONTENT_TRUST_SERVER to an http:// URL (e.g. http://notary.local), a bare hostname, or a malformed string, then performing a trusted operation (push/pull with DOCKER_CONTENT_TRUST=1). trust.Server parses it with url.Parse and rejects non-https schemes.

Common situations: Pointing at a self-hosted Notary over plain HTTP during development, a typo in the env var, a reverse proxy terminating TLS that the client still sees as http, or copy-pasting a URL without the scheme.

Related errors

• unable to resolve docker endpoint
• unable to get system cert pool
• error: no trust data available for remote repository
• error: remote repository
• error: trust data missing for remote repository

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

Appendix: source

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

// certificateDirectory returns the directory containing
// TLS certificates for the given server. An error is
// returned if there was an error parsing the server string.
func certificateDirectory(server string) (string, error) {
	u, err := url.Parse(server)
	if err != nil {
		return "", err
	}

	return filepath.Join(config.Dir(), "tls", u.Host), nil
}

// Server returns the base URL for the trust server.
func Server(indexName string) (string, error) {
	if s := os.Getenv("DOCKER_CONTENT_TRUST_SERVER"); s != "" {
		urlObj, err := url.Parse(s)
		if err != nil || urlObj.Scheme != "https" {
			return "", fmt.Errorf("valid https URL required for trust server, got %s", s)
		}

		return s, nil
	}
	if indexName == "docker.io" || indexName == "index.docker.io" {
		return NotaryServer, nil
	}
	return "https://" + indexName, nil
}

type simpleCredentialStore struct {
	auth registrytypes.AuthConfig
}

func (scs simpleCredentialStore) Basic(*url.URL) (string, string) {
	return scs.auth.Username, scs.auth.Password
}

View on GitHub (pinned to 4f84911bfe)