crowdsecurity/crowdsec · error

ErrFeatureUnknown

ErrFeatureUnknown

Error message

unknown feature

What it means

Sentinel error ErrFeatureUnknown returned by GetFeature when the requested name is not present in the feature registry (fr.features map miss). The feature flag framework only knows names registered at init time.

Source

Thrown at pkg/fflag/features.go:46

import (
	"errors"
	"fmt"
	"io"
	"os"
	"regexp"
	"sort"
	"strings"

	"github.com/goccy/go-yaml"
	"github.com/sirupsen/logrus"
)

var (
	ErrFeatureNameEmpty   = errors.New("name is empty")
	ErrFeatureNameCase    = errors.New("name is not lowercase")
	ErrFeatureNameInvalid = errors.New("invalid name (allowed a-z, 0-9, _, .)")
	ErrFeatureUnknown     = errors.New("unknown feature")
	ErrFeatureDeprecated  = errors.New("the flag is deprecated")
	ErrFeatureRetired     = errors.New("the flag is retired")
)

const (
	ActiveState     = iota // the feature can be enabled, and its description is logged (Info)
	DeprecatedState        // the feature can be enabled, and a deprecation message is logged (Warning)
	RetiredState           // the feature is ignored and a deprecation message is logged (Error)
)

type Feature struct {
	Name  string
	State int // active, deprecated, retired

	// Description should be a short sentence, explaining the feature.
	Description string

	// DeprecationMessage is used to inform the user of the behavior that has

View on GitHub (pinned to 909b515798)

Solutions

1. List available features ('cscli features list') and use an exact registered name
2. Remove the unknown feature entry from your config or env after upgrading
3. Check the changelog for feature flag renames between your versions

Example fix

// before
featureFlags.Set("enable_auto_update") // removed in this version
// after
featureFlags.Set("enable_notification_dir")

if _, err := fflag.GetFeature(name); errors.Is(err, fflag.ErrFeatureUnknown) { log.Warnf("unknown feature %q", name) }

if _, err := fflag.GetFeature(name); errors.Is(err, fflag.ErrFeatureUnknown) { return fmt.Errorf("feature %s does not exist in this version", name) }

When it happens

Trigger: GetFeature or Set called with a well-formed but unregistered feature name; a feature renamed/removed in a newer crowdsec version while old config or FFLAGS env still references it.

Common situations: Upgrading crowdsec where a feature flag was renamed; typo in feature name in config.yaml feature-flags section; stale CROWDSEC_FEATURES env var from an older install.

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

• ErrFeatureNameInvalid
• ErrFeatureDeprecated
• ErrFeatureRetired
• decision with id '%d' doesn't exist: %w
• feature flag '%s': %w

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