What causes "invalid name (allowed a-z, 0-9, _, .)" in crowdsecurity/crowdsec?

Lowercase the feature name and replace invalid characters with _ or .

ErrFeatureNameInvalid

ErrFeatureNameInvalid

Error message

invalid name (allowed a-z, 0-9, _, .)

What it means

Sentinel error ErrFeatureNameInvalid returned by validateFeatureName in pkg/fflag/features.go. Feature flag names must match featureNameRexp (a-z, 0-9, _, .); any other character (uppercase, dash, space, slash) is rejected before the name is looked up.

Source

Thrown at pkg/fflag/features.go:45

package fflag

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

View on GitHub (pinned to 909b515798)

Solutions

Lowercase the feature name and replace invalid characters with _ or .
Run 'cscli features list' (or inspect pkg/fflag features list) to copy the exact allowed feature names
Check the env var value (e.g. CROWDSEC_FEATURES) for stray characters or quotes

Example fix

// before
featureFlags.Set("Enable-Appsec")
// after
featureFlags.Set("enable_appsec")

Defensive patterns

Strategy: validation

Validate before calling

var validName = regexp.MustCompile(`^[a-z0-9_.]+$`)
if !validName.MatchString(name) { return fmt.Errorf("invalid feature name %q", name) }

Try / catch

if err := fflag.Set(name); errors.Is(err, fflag.ErrFeatureNameInvalid) { log.Warnf("bad feature name %q", name) }

Prevention

Keep feature names lowercase with only a-z, 0-9, _ and .
Copy names from 'cscli features list' instead of typing them
Trim env var values before passing them as feature names

When it happens

Trigger: Calling fflag Set/SetFromEnv/SetFromYaml/GetFeature with a name containing characters outside [a-z0-9_.], e.g. an env var mapped to a feature name with dashes or uppercase letters.

Common situations: Typo in feature flag name in config YAML or environment variable; copy-pasted names from another project using different naming conventions; manually crafted FFLAGS env value.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

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