docker/cli · error

failed to list TLS files for context

Error message

failed to list TLS files for context %s: %w

What it means

Returned by ContextStore.ListTLSFiles / tlsStore.listContextData when os.ReadDir of the context's TLS dir fails for a reason other than not-exist (not-exist returns an empty map). The dir exists but cannot be read.

Solutions

1. Fix permissions on the context's TLS dir ~/.docker/contexts/tls/<hash>.
2. Recreate the context's TLS material if the dir is damaged.
3. Confirm the running user has read/execute on the directory.

files, err := store.ListTLSFiles(ctx)
if err != nil {
    var perr *os.PathError
    if errors.As(err, &perr) && errors.Is(perr.Err, os.ErrPermission) {
        // fix read/execute perms on the tls dir, then retry
    }
    return err
}

When it happens

Trigger: Calling ListTLSFiles(ctx) when the TLS dir exists but is unreadable: permission denied, I/O error, or the path became invalid mid-operation.

Common situations: Permission denied on the TLS dir (owned by another user); corrupted filesystem; permission reset after restore.

Understand the failure class

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

Related errors

• failed to read TLS data for endpoint
• failed to remove metadata
• failed to read metadata
• failed to remove context
• failed to remove TLS data

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

Appendix: source

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

	}
	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) {
				continue
			}
			if err != nil {
				return nil, fmt.Errorf("failed to list TLS files for endpoint %s: %w", epFS.Name(), err)
			}
			var files EndpointFiles
			for _, fs := range fss {
				if !fs.IsDir() {
					files = append(files, fs.Name())
				}
			}
			r[epFS.Name()] = files

View on GitHub (pinned to 4f84911bfe)