crowdsecurity/crowdsec · error

cannot use TLS with a unix socket

Error message

cannot use TLS with a unix socket

What it means

The LAPI client Load validates that TLS client-side settings and unix socket transport are not combined. TLS certificate verification and server authentication (ca_cert_path or client cert/key auth) only make sense over TCP, so a URL starting with '/' (unix socket) plus TLS credentials is rejected at config load time.

Source

Thrown at pkg/csconfig/api.go:183

	}

	if l.Credentials != nil && l.Credentials.URL != "" {
		// don't append a trailing slash if the URL is a unix socket
		if strings.HasPrefix(l.Credentials.URL, "http") && !strings.HasSuffix(l.Credentials.URL, "/") {
			l.Credentials.URL += "/"
		}
	}

	// is the configuration asking for client authentication via TLS?
	credTLSClientAuth := l.Credentials.CertPath != "" || l.Credentials.KeyPath != ""

	// is the configuration asking for TLS encryption and server authentication?
	credTLS := credTLSClientAuth || l.Credentials.CACertPath != ""

	credSocket := strings.HasPrefix(l.Credentials.URL, "/")

	if credTLS && credSocket {
		return errors.New("cannot use TLS with a unix socket")
	}

	if credTLSClientAuth && l.Credentials.Login != "" {
		return errors.New("user/password authentication and TLS authentication are mutually exclusive")
	}

	if l.InsecureSkipVerify == nil {
		apiclient.InsecureSkipVerify = false
	} else {
		apiclient.InsecureSkipVerify = *l.InsecureSkipVerify
	}

	if l.Credentials.CACertPath != "" {
		caCert, err := os.ReadFile(l.Credentials.CACertPath)
		if err != nil {
			return fmt.Errorf("failed to load cacert: %w", err)
		}

View on GitHub (pinned to 909b515798)

Solutions

1. Remove ca_cert_path and client cert/key entries from the api.client credentials when using a unix socket
2. Or switch the url back to an https:// address if TLS is actually required
3. Keep unix socket configs minimal: url, login, password only

Example fix

// before
api:
  client:
    credentials:
      url: /run/crowdsec/lapi.sock
      ca_cert_path: /etc/crowdsec/ssl/ca.crt
// after
api:
  client:
    credentials:
      url: /run/crowdsec/lapi.sock
      login: lapi-user
      password: secret

if strings.HasPrefix(l.Credentials.URL, "/") &&
   (l.Credentials.CertPath != "" || l.Credentials.KeyPath != "" || l.Credentials.CACertPath != "") {
    return errors.New("drop TLS settings when using a unix socket url")
}
if err := l.Load(); err != nil { ... }

func isUnixSocketURL(u string) bool { return strings.HasPrefix(u, "/") }

if err := clientCfg.Load(); err != nil {
    return fmt.Errorf("lapi client config: %w", err)
}

When it happens

Trigger: config.yaml api.client has credentials.url pointing to a unix socket path (e.g. /run/crowdsec/lapi.sock) while also setting ca_cert, client cert/key, or a non-empty CACertPath; LocalApiClientCfg.Load() detects both conditions.

Common situations: Copying a TLS-enabled remote-API client config and switching to a local unix socket without removing ca/client cert entries; packaged configs that ship TLS blocks by default.

Understand the failure class

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

Related errors

• user/password authentication and TLS authentication are mutu
• could not access CRL file: %w
• allowed_ou configuration contains invalid empty string
• empty cti key
• no listen_uri or listen_socket specified

AI-assisted analysis of crowdsecurity/crowdsec@909b515798 (2026-09-06). Data as JSON: /api/errors/7440cc416e08a9db. Report an issue: GitHub.