docker/cli · error

failed to remove TLS data for endpoint

Error message

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

What it means

Returned by tlsStore.removeEndpoint (via ContextStore.ResetEndpointTLSMaterial) when os.RemoveAll of a single endpoint's TLS directory fails.

Solutions

1. Fix permissions on the endpoint TLS dir ~/.docker/contexts/tls/<hash>/<endpoint>/.
2. Remove the endpoint TLS directory manually as the appropriate user.
3. Retry the reset after correcting ownership.

if err := store.ResetEndpointTLSMaterial(ctx, ep, data); err != nil {
    if errors.Is(err, os.ErrPermission) {
        // fix perms on the endpoint tls dir, then retry
    }
    return err
}

When it happens

Trigger: Calling ResetEndpointTLSMaterial(ctx, endpoint, data) when that endpoint's TLS subdir cannot be removed — permissions, read-only filesystem, or locked files.

Common situations: Permission denial on the endpoint subdir; files locked by another process; read-only mount.

Understand the failure class

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

Related errors

• failed to remove TLS data
• unable to create docker endpoint config
• failed to remove metadata
• failed to remove context
• failed to read TLS data for endpoint

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

Appendix: source

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

		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
}

func (s *tlsStore) listContextData(name string) (map[string]EndpointFiles, error) {
	contextDir := s.contextDir(name)
	epFSs, err := os.ReadDir(contextDir)
	if err != nil {
		if os.IsNotExist(err) {
			return map[string]EndpointFiles{}, nil
		}
		return nil, fmt.Errorf("failed to list TLS files for context %s: %w", name, err)
	}
	r := make(map[string]EndpointFiles)
	for _, epFS := range epFSs {
		if epFS.IsDir() {
			fss, err := os.ReadDir(filepath.Join(contextDir, epFS.Name()))
			if os.IsNotExist(err) {

View on GitHub (pinned to 4f84911bfe)