crowdsecurity/crowdsec · error

unable to load outofband rule %s : %s

Error message

unable to load outofband rule %s : %s

What it means

Returned by AppsecRuntimeConfig Build when loading an out-of-band (WAF) rule collection via LoadCollection fails. LoadCollection resolves the rule name against the hub and parses its YAML into rule collections; any resolution or parse failure is wrapped here. It blocks startup of the appsec engine for that config.

Source

Thrown at pkg/appsec/appsec.go:945

			wc.DefaultRemediation, wc.Name, BanRemediation, CaptchaRemediation, AllowRemediation, ChallengeRemediation)
	}

	ret.Name = wc.Name
	ret.Config = wc
	ret.DefaultRemediation = wc.DefaultRemediation
	ret.BodySettings = BodySettings{
		MaxSize: DefaultMaxBodySize,
		Action:  BodySizeActionDrop,
	}

	wc.Logger.Tracef("Loading config %+v", wc)
	// load rules
	for _, rule := range wc.OutOfBandRules {
		wc.Logger.Infof("loading outofband rule %s", rule)

		collections, err := LoadCollection(rule, wc.Logger.WithField("component", "appsec_collection_loader"), hub)
		if err != nil {
			return nil, fmt.Errorf("unable to load outofband rule %s : %s", rule, err)
		}

		ret.OutOfBandRules = append(ret.OutOfBandRules, collections...)
	}

	wc.Logger.Infof("Loaded %d outofband rules", len(ret.OutOfBandRules))

	for _, rule := range wc.InBandRules {
		wc.Logger.Infof("loading inband rule %s", rule)

		collections, err := LoadCollection(rule, wc.Logger.WithField("component", "appsec_collection_loader"), hub)
		if err != nil {
			return nil, fmt.Errorf("unable to load inband rule %s : %s", rule, err)
		}

		ret.InBandRules = append(ret.InBandRules, collections...)
	}

View on GitHub (pinned to 909b515798)

Solutions

1. Fix the rule name in the appsec-config's outofband_rules list (check spelling against `cscli collections list`)
2. Run `cscli hub update && cscli hub upgrade` and install the missing collection
3. Validate the custom rule YAML syntax and its referenced expressions
4. Check the wrapped error (%s) for the underlying cause — parse error vs not-found

Example fix

// before (appsec-config.yaml)
outofband_rules:
  - crowdsecurity/appsec-rule
// after
outofband_rules:
  - crowdsecurity/appsec-rules

for _, rule := range cfg.OutOfBandRules {
    if !cscliCollectionExists(rule) {
        return fmt.Errorf("outofband rule %q not installed", rule)
    }
}

if _, err := buildAppsecRuntime(cfg); err != nil {
    if strings.Contains(err.Error(), "unable to load outofband rule") {
        log.Fatalf("fix outofband_rules entries / hub state: %v", err)
    }
    return err
}

When it happens

Trigger: Build() iterating wc.OutOfBandRules and calling LoadCollection(rule, ...) which errors because the collection name is not installed in the hub, the YAML file is malformed, or referenced expressions/parsers are missing.

Common situations: Referencing a non-existent collection in `outofband_rules:`; hub not synced/upgraded so files are missing; a custom rule YAML with invalid syntax; stale hub state after a version upgrade.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• unable to load inband rule %s : %s
• no appsec_config provided
• no zones defined
• no match type defined
• no match value defined

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