crowdsecurity/crowdsec · error

stream_name is mandatory when use_enhanced_fanout is false

Error message

stream_name is mandatory when use_enhanced_fanout is false

What it means

The kinesis acquisition source requires a way to identify the target stream. When use_enhanced_fanout is false, the source reads from the shared stream consumer, which is addressed by stream name, so Configuration.Validate() rejects configs where StreamName is empty. Enhanced fan-out mode instead identifies the stream by ARN, which is why the name is only mandatory in non-fan-out mode.

Source

Thrown at pkg/acquisition/modules/kinesis/config.go:77

	if c.MaxRetries <= 0 {
		c.MaxRetries = 10
	}
}

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.StreamName == "" && !c.UseEnhancedFanOut {
		return errors.New("stream_name is mandatory when use_enhanced_fanout is false")
	}

	if c.StreamARN == "" && c.UseEnhancedFanOut {
		return errors.New("stream_arn is mandatory when use_enhanced_fanout is true")
	}

	if c.ConsumerName == "" && c.UseEnhancedFanOut {
		return errors.New("consumer_name is mandatory when use_enhanced_fanout is true")
	}

	if c.StreamARN != "" && c.StreamName != "" {
		return errors.New("stream_arn and stream_name are mutually exclusive")
	}

	return nil
}

func (s *Source) Configure(ctx context.Context, yamlConfig []byte, logger *log.Entry, metricsLevel metrics.AcquisitionMetricsLevel) error {

View on GitHub (pinned to 909b515798)

Solutions

1. Set stream_name in the kinesis acquisition YAML config (e.g. stream_name: my-log-stream).
2. If you intended enhanced fan-out mode, set use_enhanced_fanout: true and provide stream_arn (and consumer_name) instead of stream_name.
3. Run `cscli` acquisition validation or a local Validate() call before deploying to catch this early.

Example fix

// before (yaml)
source: kinesis
stream_arn: arn:aws:kinesis:us-east-1:123456789012:stream/logs

// after (yaml)
source: kinesis
stream_name: logs
# or, for fan-out:
# use_enhanced_fanout: true
# stream_arn: arn:aws:kinesis:us-east-1:123456789012:stream/logs
# consumer_name: crowdsec-consumer

if cfg.UseEnhancedFanOut == false && cfg.StreamName == "" {
    return fmt.Errorf("kinesis: stream_name is required when use_enhanced_fanout is false")
}

When it happens

Trigger: Calling Validate() on a kinesis Configuration where UseEnhancedFanOut is false (or unset) and StreamName is the empty string.

Common situations: A YAML acquisition entry for kinesis that omits the stream_name key, or uses stream_arn alone without enabling use_enhanced_fanout: true. Also happens when stream_name is set via a template/variable that expands to empty.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• stream_arn is mandatory when use_enhanced_fanout is true
• consumer_name is mandatory when use_enhanced_fanout is true
• stream_arn and stream_name are mutually exclusive
• cannot create kinesis client: %w
• failed to load aws config: %w

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