harness/harness · critical

provided concurrency %d is invalid - has to be between 1 and

Error message

provided concurrency %d is invalid - has to be between 1 and %d

What it means

Go library (stream package) panics from the WithConcurrency consumer option when the supplied concurrency is outside [1, MaxConcurrency] (MaxConcurrency = 64). The package deliberately panics instead of returning an error to keep the functional-options API clean — an invalid concurrency is treated as a programmer misconfiguration that should crash loudly at startup rather than silently degrade.

Source

Thrown at stream/options.go:50

// ConsumerOption is used to configure consumers.
type ConsumerOption interface {
	apply(*ConsumerConfig)
}

// consumerOptionFunc allows to have functions implement the ConsumerOption interface.
type consumerOptionFunc func(*ConsumerConfig)

// Apply calls f(config).
func (f consumerOptionFunc) apply(config *ConsumerConfig) {
	f(config)
}

// WithConcurrency sets up the concurrency of the stream consumer.
func WithConcurrency(concurrency int) ConsumerOption {
	if concurrency < 1 || concurrency > MaxConcurrency {
		// misconfiguration - panic to keep options clean
		panic(fmt.Sprintf("provided concurrency %d is invalid - has to be between 1 and %d",
			concurrency, MaxConcurrency))
	}
	return consumerOptionFunc(func(c *ConsumerConfig) {
		c.Concurrency = concurrency
	})
}

// WithHandlerOptions sets up the default handler options of a stream consumer.
func WithHandlerOptions(opts ...HandlerOption) ConsumerOption {
	return consumerOptionFunc(func(c *ConsumerConfig) {
		for _, opt := range opts {
			opt.apply(&c.DefaultHandlerConfig)
		}
	})
}

// HandlerOption is used to configure the handler consuming a single stream.
type HandlerOption interface {

View on GitHub (pinned to 828c7abf3a)

Solutions

1. Clamp the value before passing it: concurrency = min(max(concurrency, 1), stream.MaxConcurrency).
2. If the value comes from config/env, validate and fail with a clear configuration error message before constructing the consumer.
3. Raise the value only if you truly need >64 concurrent handlers; otherwise scale consumers horizontally rather than raising concurrency.
4. Check the option against the exported stream.MaxConcurrency constant (64) instead of hardcoding the number, so upgrades stay correct.

Example fix

// before
consumer := stream.NewConsumer(name, handler,
  stream.WithConcurrency(cfg.Concurrency), // panics if 0 or >64
)

// after
concurrency := cfg.Concurrency
if concurrency < 1 || concurrency > stream.MaxConcurrency {
  return fmt.Errorf("invalid concurrency %d: must be 1..%d", concurrency, stream.MaxConcurrency)
}
consumer := stream.NewConsumer(name, handler,
  stream.WithConcurrency(concurrency),
)

// validate before constructing the consumer
func validConcurrency(n int) bool { return n >= 1 && n <= stream.MaxConcurrency }

if !validConcurrency(cfg.Concurrency) {
  return fmt.Errorf("concurrency %d out of range [1,%d]", cfg.Concurrency, stream.MaxConcurrency)
}

When it happens

Trigger: Calling stream.WithConcurrency(n) with n < 1 (including 0, e.g. an uninitialised int or a computed value that underflowed) or n > 64 (e.g. pulled from an env var or config file without clamping). The panic occurs at Consumer construction time, before any messages flow.

Common situations: Reading concurrency from a config map with a missing key defaulting to 0; deriving concurrency from runtime.NumCPU() multiplied by a factor exceeding 64; passing a user-supplied CLI flag straight through; copying example code that assumed a higher cap after a library version with different limits.

Related errors

• provided maxRetries %d is invalid - has to be between 0 and
• provided timeout %d is invalid - has to be longer than %s
• failed to load embedded files: %w
• failed to read remote entry JS content: %w
• failed to create file map for dist folder: %w

AI-assisted analysis of harness/harness@828c7abf3a (2026-08-15). Data as JSON: /api/errors/476daa48262b87c9. Report an issue: GitHub.