What causes "path must start with /" in crowdsecurity/crowdsec?

Add a leading slash to the path value: `path: /api/events`.

path must start with /

Error message

path must start with /

What it means

CrowdSec's HTTP acquisition module requires the `path` config field (the URL path of the endpoint to poll/POST to) to be an absolute path beginning with '/'. Configuration.Validate() checks c.Path[0] != '/' and rejects anything else before the datasource is ever started. This is a static config validation error, not a runtime failure.

Source

Thrown at pkg/acquisition/modules/http/config.go:100

func (s *Source) UnmarshalConfig(yamlConfig []byte) error {
	cfg, err := ConfigurationFromYAML(yamlConfig)
	if err != nil {
		return err
	}

	s.Config = cfg

	return nil
}

func (c *Configuration) Validate() error {
	if c.ListenAddr == "" && c.ListenSocket == "" {
		return errors.New("listen_addr or listen_socket is required")
	}

	if c.Path[0] != '/' {
		return errors.New("path must start with /")
	}

	switch c.AuthType {
	case "basic_auth":
		baseErr := "basic_auth is selected, but"
		if c.BasicAuth == nil {
			return errors.New(baseErr + " basic_auth is not provided")
		}

		if c.BasicAuth.Username == "" {
			return errors.New(baseErr + " username is not provided")
		}

		if c.BasicAuth.Password == "" {
			return errors.New(baseErr + " password is not provided")
		}
	case "headers":
		if c.Headers == nil {

View on GitHub (pinned to 909b515798)

Solutions

Add a leading slash to the path value: `path: /api/events`.
If you put a full URL in `path`, keep only the path portion and move scheme/host into the base URL/listen config fields.
If the value comes from an env var or template, ensure the resolved value starts with '/'.
If `path` is optional for your setup, omit the key rather than setting it to an empty string (check the module's defaults).

Example fix

// before (config.yaml)
source: http
path: api/events

// after
source: http
path: /api/events

Defensive patterns

Strategy: validation

Validate before calling

func validHTTPPath(p string) bool { return strings.HasPrefix(p, "/") }
if !validHTTPPath(cfg.Path) { return fmt.Errorf("path %q must start with /", cfg.Path) }

Prevention

Always write `path` values with a leading slash in datasource configs.
Never place a full URL in `path`; keep scheme/host out of it.
Validate config in CI with a lint step before deploying crowdsec.
When interpolating env vars into `path`, assert the result starts with '/'.

When it happens

Trigger: Configure an http datasource whose `path` field is empty, missing its leading slash (e.g. `path: api/events`), or is a full URL instead of a path (e.g. `path: https://host/api`). Any call to Configuration.Validate() with such a config returns this error.

Common situations: Users paste a full URL into `path` when only the path portion belongs there; YAML values like `path: metrics` copied from examples that changed; empty string when the key exists but the value was removed; interpolation of an env var that resolves to something without a leading slash.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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