docker/cli · error

failed to read TLS data for endpoint

Error message

failed to read TLS data for endpoint %s: %w

What it means

Returned by tlsStore.getData when reading a TLS file fails for a reason other than not-exist: the file exists but os.ReadFile errors (permission denied, I/O error, path became invalid).

Solutions

1. Fix permissions on the TLS file under ~/.docker/contexts/tls/<hash>/<endpoint>/.
2. Re-import the TLS material if the file is damaged or replaced.
3. Ensure the running user can read 0600 files in that endpoint dir.

data, err := store.GetTLSData(ctx, ep, file)
if err != nil {
    var perr *os.PathError
    if errors.As(err, &perr) && errors.Is(perr.Err, os.ErrPermission) {
        // fix perms on the file/dir, or re-import TLS material
    }
    return err
}

When it happens

Trigger: Calling GetTLSData when the TLS file exists but is unreadable: permission denied because it is owned by another user, a disk/read error, or the file was removed/replaced between listing and reading.

Common situations: Files owned by root but CLI as a normal user; failing disk; permission reset after a backup restore; race with concurrent cleanup.

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• failed to list TLS files for context
• failed to remove metadata
• failed to remove context
• failed to remove TLS data
• failed to remove TLS data for endpoint

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

Appendix: source

Thrown at cli/context/store/tlsstore.go:43

func (s *tlsStore) createOrUpdate(name, endpointName, filename string, data []byte) error {
	parentOfRoot := filepath.Dir(s.root)
	if err := os.MkdirAll(parentOfRoot, 0o755); err != nil {
		return err
	}
	endpointDir := s.endpointDir(name, endpointName)
	if err := os.MkdirAll(endpointDir, 0o700); err != nil {
		return err
	}
	return atomicwriter.WriteFile(filepath.Join(endpointDir, filename), data, 0o600)
}

func (s *tlsStore) getData(name, endpointName, filename string) ([]byte, error) {
	data, err := os.ReadFile(filepath.Join(s.endpointDir(name, endpointName), filename))
	if err != nil {
		if os.IsNotExist(err) {
			return nil, notFound(fmt.Errorf("TLS data for %s/%s/%s does not exist", name, endpointName, filename))
		}
		return nil, fmt.Errorf("failed to read TLS data for endpoint %s: %w", endpointName, err)
	}
	return data, nil
}

// remove deletes all TLS data for the given context.
func (s *tlsStore) remove(name string) error {
	if err := os.RemoveAll(s.contextDir(name)); err != nil {
		return fmt.Errorf("failed to remove TLS data: %w", err)
	}
	return nil
}

func (s *tlsStore) removeEndpoint(name, endpointName string) error {
	if err := os.RemoveAll(s.endpointDir(name, endpointName)); err != nil {
		return fmt.Errorf("failed to remove TLS data for endpoint %s: %w", endpointName, err)
	}
	return nil
}

View on GitHub (pinned to 4f84911bfe)