crowdsecurity/crowdsec · error

while parsing capi whitelist file '%s': %w

Error message

while parsing capi whitelist file '%s': %w

What it means

After successfully opening the capi whitelist file, LoadCapiWhitelists parses it as YAML via parseCapiWhitelists, which also validates each entry as an IP (netip.ParseAddr) or CIDR (netip.ParsePrefix). Any parse/validation failure — including an empty file — is wrapped with this prefix.

Source

Thrown at pkg/csconfig/api.go:506

}

func (c *LocalApiServerCfg) LoadCapiWhitelists() error {
	if c.CapiWhitelistsPath == "" {
		return nil
	}

	log.Warn("capi_whitelists_path is deprecated, please use centralized allowlists instead. See https://docs.crowdsec.net/docs/next/local_api/centralized_allowlists.")

	fd, err := os.Open(c.CapiWhitelistsPath)
	if err != nil {
		return fmt.Errorf("while opening capi whitelist file: %w", err)
	}

	defer fd.Close()

	c.CapiWhitelists, err = parseCapiWhitelists(fd)
	if err != nil {
		return fmt.Errorf("while parsing capi whitelist file '%s': %w", c.CapiWhitelistsPath, err)
	}

	return nil
}

func (c *Config) LoadAPIClient() error {
	if c.API == nil || c.API.Client == nil || c.API.Client.CredentialsFilePath == "" || c.DisableAgent {
		return errors.New("no API client section in configuration")
	}

	return c.API.Client.Load()
}

func (c *LocalApiServerCfg) LoadAutoRegister() error {
	if c.AutoRegister == nil {
		c.AutoRegister = &LocalAPIAutoRegisterCfg{
			Enable: new(false),
		}

View on GitHub (pinned to 909b515798)

Solutions

1. Read the inner error: it names the invalid value or 'empty file'
2. Populate the file with valid `ips:` / `cidrs:` YAML lists, or delete it and unset capi_whitelists_path
3. Validate each entry (`ipcalc`, `python3 -c "import ipaddress;ipaddress.ip_network('10.0.0.0/8')"`)
4. Migrate to centralized allowlists, which have tooling to catch bad entries

Example fix

// before (capi_whitelists.yaml)
cidrs:
  - 192.168.0.0/16
  - 10.0.0.0/33
// after
cidrs:
  - 192.168.0.0/16
  - 10.0.0.0/8

for _, c := range cidrs {
	if _, err := netip.ParsePrefix(c); err != nil { return fmt.Errorf("bad cidr %q: %w", c, err) }
}
for _, ip := range ips {
	if _, err := netip.ParseAddr(ip); err != nil { return fmt.Errorf("bad ip %q: %w", ip, err) }
}

if err := serverCfg.LoadCapiWhitelists(); err != nil {
	if strings.Contains(err.Error(), "while parsing capi whitelist") {
		log.Fatalf("fix %s: %v", serverCfg.CapiWhitelistsPath, err)
	}
	return err
}

When it happens

Trigger: capi_whitelists_path file exists but contains invalid YAML, an empty file, a malformed IP in the `ips` list, or a malformed CIDR in the `cidrs` list.

Common situations: Empty placeholder file created with `touch`; hand-written entry like `192.168.1.0/24 ` with stray characters or `10.0.0.1/33` invalid prefix; YAML tabs instead of spaces.

Related errors

• empty file
• parsing console config file '%s': %w
• document %d: %w
• failed to parse %s: %w
• missing allowed_ranges value for api.server.auto_register

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